exploration of available out-of-the-box documentation tooling options

[MaxDiz]

Based on the CHT documentation site functional requirements (#193), we want to do a review of available out-of-the-box solutions that most closely match user needs. This ticket is to document potential solutions and key considerations for decision making on documentation tooling options.

[MaxDiz]

Stencil has a nice documentation site that integrates with github. Side navigation bars (left and right) are well done. May be worth looking into further

[riyasingh1]

Stencil has a nice documentation site that integrates with github. Side navigation bars (left and right) are well done. May be worth looking into further

Great! I'll add it to the list :)

[riyasingh1]

In addition to the requirements listed under issue #193, I am also considering which platforms require the least dev time and allow for seamless integration with the CHT forum. Let me know if there are other considerations I should include. I am looking at the following 15 products, so please let me know if I should look into anything else: Jekyll (existing), Docusaurus, Docsify, Hugo, Hexo, Gatsby, VuePress, Next, Nuxt, Eleventy, Stencil, Gitbook, MkDocs, Gridsome, Sapper, Scully.

[riyasingh1]

Here is a link to the analysis.

[MaxDiz]

Next steps: Review top contenders from @riyasingh1 analysis and identify any blockers:

• Docusaurus (@n-orlowski )
• Hugo (@kennsippell )
• VuePress (@MaxDiz )

Ideally, there is an available theme that allows for something similar to this format: https://github.com/medic/medic.github.io/blob/2020-doc-site/new/02-features/04-contacts.md

Notes should be added in the "Second-reader" column of spreadsheet

Loop in @abbyad with any questions

[MaxDiz]

related: https://github.com/medic/medic-docs/issues/215

[abbyad]

With respect to the collapsible sections in this first pass, we'll want the following:

• ref materials for app developers to still be shown on the same over pages
• the app developer sections to be easily ignored/skipped so that overview is still readable by non-developers
• possible to link to the app developer content between sections and from outside of the site -- it is not possible to directly link to collapsed content with Github markdown

[MaxDiz]

A few additional observations below on VuePress's default theme. Generally looks like a great option out-of-the-box and could be customized in the future if needed. There also seems to be a pretty robust community for support and plug-in extensions (https://github.com/vuepressjs/awesome-vuepress#plugins)

Content Contribution

• easy to import code snippets
• auto generated GH links to make it easy to find source info
• real-time previewer plugin that would make it easier for team contributions (growi docs - see plugins link above)

Content Organization

• index- customizable nav bar and side bar. Also multiple search options that seem pretty robust
• custom containers, including an accordion style dropdown (dropdown does not work in IE)
• badging for highlighting content (ie "new" "beta" etc)
• markdown slots for more modular information management: https://v1.vuepress.vuejs.org/guide/markdown-slot.html#why-do-i-need-markdown-slot

We should take a closer look at multi-language support. I'm not sure how we are planning to handle within the site. https://v1.vuepress.vuejs.org/guide/i18n.html#site-level-i18n-config

There are a number of blog theme extensions available which may be nice for reuse of documentation content for community communication and driving doc site usership

[MaxDiz]

Continue to add reviews of tooling options here or to this doc

[abbyad]

I have explored several options, and setting up example sites and themes for each. The frontrunner for me is Hugo with Docsy theme. I am putting that out there partly to draw out any criticism for it, and seeing if something else is a better fit!

[MaxDiz]

We've decided on a tooling option for our upcoming doc site relaunch. Thanks @riyasingh1 for your leadership in helping us to assess our options!