💾 Archived View for sporiff.dev › microblog › complex captured on 2024-08-18 at 17:09:59. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
Posted on 2024-08-13
I maintain a documentation site at my place of work. Since I started writing it, we've added a lot of different tools and markup to facilitate adding bits and pieces in to the writing itself. Callouts, fancy tables, tabbed code snippets... you name it, we've got it. Since we write in MDX we can build an interface into our component library to populate it with content. Sounds good in theory, but in practice I believe it's making the documentation messier.
For my personal site, I write using Gemini markup ("Gemtext"). You can think of it as being like a very, very basic version of Markdown. The specification handles headers, single-level unordered lists, blockquotes, links (on their own line), and preformatted text blocks. That's it. You can read the full specification in about a minute.
Gemtext specification (on Gemini)
Gemtext specification (on HTTP)
This simplicity forces you to focus on how you write the actual words, rather than how you might format the words on the page. It's really nice for writing simple posts and updates, but maybe a bit limiting for technical writing. However, I feel there's a lesson to be learned here: if you can adequately express what you're trying to express without additional markup, you should.
Callouts are a good example of this. We use them all the time to highlight something as "Important" or a "Note". Callouts (or "admonitions") are often presented as colored blocks containing text, perhaps adorned with an icon. They're visually appealing and eye-catching, so you'd think they're pretty well-suited to calling out this kind of information.
Well, yes and no. See, we frequently receive feedback where users express confusion over things that are definitely answered in callouts. They aren't as attention-grabbing as one might think, and there's a reason a lot of technical documents (such as web RFCs) don't contain them. It's much better to just focus on making sure your prose is unambiguous and clearly structured.
This is all to say: I'm on a mission to clean up the use of unnecessary markup from our documentation. My approach will be to try and see how much I can do with pure Markdown in each document, akin to a Sourcehut/GitHub wiki, then to add more only if it's required.