Add documentation scheme #29
Description
One of the main goals of Ecuador in Tech repository is to expose volunteers -- usually, junior devs -- to best practices. This repository, and other from the GitHub organization, is the combined effort of senior volunteers arguing, in the intelectual sense, about what would be the best design possible, according to specs.
We should document not just the thought process, but the associated technical documents for such efforts.
We have many ways to approch this:
- GitHub wiki
- Starlight theme, from Astro
- mdBook
- Typst
- Pandoc
1. GitHub wiki
Hard pass for me. While I acknowledge this is a commonly used workflow, my main concerns in supporting this I would increment our odds to become vendor-locked; and, most importantly, it won't be available offline.
2. Starlight theme, from Astro
We are already using Astro, and there are some nift way to integrate it with our current setup. As we are in Astro territory, many of our workflows would apply, too.
I would be eager to try it out; but, there's no .pdf export. Let's not talk about manpages.
3. mdBook
One of the main success from this toolkit is The Rust Book. Written in Rust, supports docsite generation using markdown and minimal configuration. Again, no .pdf, nor manpages.
4. Typst
This is actually a TeX replacement. It has markdown-like syntax, and is a good entry-point for all the richness that's technical documentation. However, HTML export is in the works; and this is a website, so, yeaaaah...
5. Pandoc
The venerable pandoc, the "Swiss Army of Doc Converters". Wonderful. You cannot engaged in high-level professional techincal documentation if you haven't, at least, heard of it. Inputs from markdown to html, pdf, and mandoc, if your heart desires. cli interface is comfy: pandoc -fmarkdown -tpdf -i doc.md -o doc.pdf works as expected.
I put my hand in my heart and say: let's just implement Starlight inside a doc/ folder. From there, if we really need .pdf and the like, it would be a shell script using pandoc and m4, tbh.