I always like to say that documentation should live with the code, within the code or besides the code.
That’s always what I try to do, write at least some decent README, and write some documentation inside the code.
But writing a big documentation file is always a challenge, as it keeps growing, it becomes harder to maintain.
What about writing separate files and bring them together?
Use Asciidoc
I don’t know what I was thinking when I thought Markdown is problem solver and a universal documentation language.
This post is to convince you that Markdown has serious issues of compatibility, and poor scalability, as very hard to write beautiful things with it.
Ok. You can tell me that there is a lots of documentation written in markdown over there, but I can tell you for sure, that different parsers will generate different results. And besides that, those good markdown documentation are all enhanced with HTML. So, what’s the point?
Our LabVIEW Champion Olivier Jourdan is smarter than me, and he has been using for a good time in his tool Antidoc. He is truly someone ahead of our time.
But what I want to emphasize here is that Asciidoc is not difficult at all, and you can start getting fancy with it as soon as you start learning more and more.
I bet that no more than 2 or 3 documents you write with Asciidoc you will already be writing documents with the same or even better appearance than MD.
Besides, there is this feature called “include”, where you can put together other docs all in one document.
I am not saying to change all your current documentation, but from now onwards, you should consider it.
So, next time, make us a favor, write in Asciidoc. And don’t worry, Gitlab and all of big providers already render natively the Asciidoc (.adoc).
Read The Docs
Sometimes your documentation just get out of the control, and Asciidoc itself won’t solve your problems, than it is time to consider some other solutions like Read the Docs.
I put some documentation in one of my last open source projects, and I got to tell you, it wasn’t difficult at all. Maybe I will have one post on this in the future. Here is the link:
https://badges-gitlab.readthedocs.io/
With Sphinx and Readthedocs things can get really fancy, and then the limit is your imagination.
Final Thoughts
In the end, your code will be remembered to be the one that it was easy to use and integrate, or the one that had no documentation at all and never got used.
I think this is also valid for your future yourself when you touch a code which has been for a long time in its corner. Ow, it is so easy to forget how you coded something.
So, next time, use Asciidoc and forget about Markdown. I already said that, right? I am sounding repetitive, it is time to end the post.
Until the next one.
Felipe's Thoughts 