# Technical Writing > [!cite] > > *If I could go upstairs and write every day, I would be happy. I don't need recreation.* > > Henry Petroski Although a lot is written here about writing and communicating tech, I thought of having a specific page to describe my journey writing this documentation, which may serve others venturing themselves in similar quests. ==There's no better way of experimenting with how the WYSIWYG[^5] approach to creating technical documentation is morally broken than trying to write a 1,000-page document.== If you happen to find yourself in those muddy waters, you will most likely end up realizing that there's no freaking way of getting away with it with the current mainstream tools (Word, LibreOffice). It fails all around. However, some alternatives suck as well. Having written a book^[https://www.barnesandnoble.com/w/la-ciencia-dura-ignacio-chechile/1142051201] in $\LaTeX$, I can confidently say I know quite well what it means to write in such a way when the format and the content divorce forever, and you not only have to deal with what you're trying to say but also with a plethora of convoluted keywords and brackets. Writing documentation in $\LaTeX$ has the painful drawback that, when you are in "edit" mode, the syntax gets too much on your way. It becomes a visual nightmare. For writing that book, I used Overleaf^[https://www.overleaf.com/], whose editor is okay, although I had a lot of trouble with grammar checks so I was most of the time flying "manual". It helped the fact I wrote it in my mother tongue, and perhaps one thing I am proud of myself for is that my grammar in Spanish is reasonably decent. These notes started as a Word document. In a matter of months, said document **had grown to around 800 pages and 600 figures**. By the time it reached that size, I realized how screwed I was; all of a sudden, adding one new figure would take around 1 minute of my reasonably performant MacBook Pro spinning the wheels like there was no tomorrow. On top of that, when I started evaluating export possibilities, I realized it was not possible to create a PDF out of it (Word unilaterally fixes the maximum docx file size to 32MB for some reason[^10], my doc was ~80MB). And I pay for Adobe Pro. Then, I tried to experiment with this "multi-document" approach in Word where you can break a big document into smaller documents with a master one gathering all together. The export issues were still there. Then I thought of manually splitting the doc into smaller docs but what about the internal links, the table of contents, the figures? Frustrated, I went into an erratic raid around the most shady websites you can find (and of course Stack Overflow) to find workarounds that failed one after another. The more I went into this, the more I realized that a document, as a single unit, was wrong as a choice for what I was trying to do. What was I trying to do, anyway? I was trying to gather notes and thoughts, and ultimately structure knowledge, and documents were, clearly, not the right way of doing that. But what was the right way? ## A Necessary Evil: The Document As engineers, we are raised with the doctrine that documents are sacred. Everything we do must be captured in a document with a nice table of contents, logos, change log, and all that you expect for a nice, corporate-looking, professional doc. Even more in the space industry: companies that work in anything else than Word are seen as hippies. On the pros, documents are nicely self-contained; you can carry them everywhere and open them even when your internet connection is nonexistent. Documents are easier to review than a Wiki because their conception is rather straightforward and linear: the outline takes you from beginning to end. But documents are also heavily cursed: copying a document takes almost no effort, which means that outdated versions spread faster than the flu in winter. Are we getting rid of documents anytime soon? I personally don't think so. They keep on serving a purpose as long as you keep them below 50-60 pages. Get near 100 pages or more, and documents stop making any sense at all. But what is the alternative then? It clearly calls for a radically different approach than the document. That's why is quite weird to see people adopting things like Confluence but still writing it as a document. I mean, the whole idea of a wiki is that you don't need to have rigid outlines and you can exploit things as embedding video and other more interactive things, isn't it? ## Goodbye Cruel Word; Hello Markdown, I guess So there I was, lost on how to proceed and with nearly 250,000 words looking at me, asking for a home. I cringed at the possibility of going back to $\LaTeX$. I was so much not trying anything like XML or HTML (hell no); what kind of sadistic monster can write a document in HTML? So I needed an alternative. The more I was going into this, the more markdown appeared as a surprisingly decent option. I knew markdown from the GitHub readme files and Slack, and I was always somewhat captivated by its lightweight style. When you are in Edit mode, The next question was: how the hell do I go from my docx to markdown? What is more, what do I use to render the markdown content? ## Exporting from Word to Markdown: On The Highway to Hell If you'd ask me: how did it go to export nearly 250,000 words, formulas, and hundreds of images from Word into markdown? I would say, it went as wrong as I was expecting it'd go. I was not expecting it'd be a cakewalk, and oh my, it wasn't. I remember trying to import the .md file I got from `pandoc` in Confluence, to amusing results. Confluence just froze, my browser needed a forced quit, and if I recall correctly, all this operation included a hard reboot of my laptop. Once I got from StackOverflow the right amount of magic flags of `pandoc`, the result was ok. Still, all figures were absolutely wrong, all captions were lost, and a long, long way of manual work was waiting for me, just around the corner. I realized it didn't make much more sense to continue experimenting with markdown without having a tool to, well, render it. I evaluated the usual suspects: Notion^[https://www.notion.so/], Roam Research^[https://roamresearch.com/], Gitbook^[https://app.gitbook.com/], and Obsidian^[https://obsidian.md/]. I was also interested in making my notes public, so Obsidian Publish^[https://obsidian.md/publish] appeared as a decent option. I went for it, and I haven't regretted it (yet). Obsidian, although surprisingly decent, brought me back to a ghost I thought I had left behind when I stopped fiddling with WordPress: plugins and CSS back magic. I wasn't ready to come back to it. ## The Bog of Eternal Stench: Plugins and CSS Snippets As soon as you abandon the bog of eternal stench WYSIWYG is, you enter another one: the bog of plugins and obscure, copied-and-pasted-from-StackOverflow CSS snippets. Whoever has experimented with any publishing platforms like WordPress (and is not a web developer, like me) has had to deal with CSS black magic and plugins written in JavaScript that never work the first time you try. CSS, or Cascading Style Sheets, is a sort of holy cow in web design, allowing those developers who understand how it works to apply stylistic choices to web documents. Unlike HTML, which only structures content, CSS focuses on layout, color, typography, and the overall presentation of a page. Its cascading nature means that styles can be defined in multiple layers, with an obscure hierarchy that determines how conflicting styles are resolved, ensuring some consistent and dynamic user experience across different devices and screen sizes. CSS operates through selectors and declarations. Selectors target HTML elements, while declarations, encapsulated within curly braces, define how these elements should be styled. CSS code tends to sit on its own .css files. You can do basically anything you want with CSS, as long as it's not centering an image or anything like that. I like to think of the CSS acronym more as a _Constantly Suffering Syndrome_. CSS is supposed to make websites look nice, but half the time, it feels like trying to put a leash on a cat. You think it's going to be straightforward, but no, it's a battle of wills. Most of the time, I don't want anything fancy; I just want to style a paragraph, or center a goddamn image, not perform a synchronized swimming routine. In general, nothing works. Soon, because some random dude in StackOverflow tells you to, you start adding the `!important` keyword everywhere. It works! Before you realize it, everything is `!important` in your crappy CSS code. It makes you think: if absolutely everything is important, nothing is. Now the stuff works. Cross-browser compatibility? Thank you very much. You spend hours, and days, tweaking, and adjusting until things more or less work, only to find out that your phone browser ignores all your CSS rules, and everything looks awfully cropped. Oh well.  > [!Figure] > _Me doing CSS_ And, oh, the plugins. I have to thank those random guys on the Internet for taking the time to write thousands of lines of JavasScript that do exactly what you need although you have no flying idea why it works. Image captions? Needs a plugin and the only one is a plugin with 2.1 stars in reviews and abandoned since 2013. Adding a pull quote? Another plugin. Thank you, random strangers. ## Obsidian: Surprisingly Decent I was longing for a tool that would: - Render markdown - Allow me to go through the "writing->publishing->correcting->repeat" cycle as straightforward as possible. - Have grammar check and all the tools to ensure there are as few typos as possible - Would be responsive enough (even for a big word count) and work decently offline. So used as I am to shitty tools, I was gladly surprised by the decency of Obsidian. It checked most, if not all of these requirements above. The quite big minus of Obsidian are figures: adding captions and numbering them is just impossible. Also, Obsidian Publish does not seem to be the most mature product ever so new things are coming up all the time, for the good or the worse. ## Conclusion Hey, I want to finish this with a message of hope. If you are writing technical documentation about something, drop documents and consider markdown. Sure, it won't be a bed of roses, but it will be way better than handling a humongous docx file that will give you nightmares forever. When jumping into the markdown wagon, consider the costs of the platforms you choose, and take into account the special features and syntax said platform may have that might not be compatible with the markdown specification; if you go too hard on those, migrating to some other platform may prove complicated. [^10]: As per Microsoft, the maximum file size is limited to 32 MB for the total document—text only—and does not include graphics, regardless of how the graphics image is inserted into the document. Therefore, if the file contains graphics, the maximum file size can be larger than 32 MB. [^5]: For the uninitiated, WYSIWYG stands for "What You See Is What You Get" and it describes a philosophy of creating content where format always closely resembles its appearance when displayed or printed. This approach allows users to format text, graphics, and other elements on a document or interface directly, showing the effects of changes in real-time, thus reducing the need to visualize the end result or understand complex coding or formatting commands.