Choose a documentation platform

[thatplguy]

There are currently four sources of CN documentation in varying states of completeness with some overlap:

• the CN README in plain github markdown
• the CN tutorial using asciidoctor
• the CN manual in plain github markdown
• this CN language reference in GitBooks

We should consolidate. Here are the requirements I see for a doc platform:

• Doc generator is open source, supported/actively developed, and has good docs itself
• Document navigation to move between types of docs (tutorial, language reference, etc.) and within each doc
• A mechanism to automatically test all code snippets in CI
• Good default styling, or easy to implement styling – under the assumption that good aesthetic design makes docs nicer to use

Some nice-to-have features:

• Supports user analytics, e.g. Google Analytics, for collecting HCI data
• Markdown (more widely used than asciidoctor, restructured text, etc. AFAIK)
• Support for callouts, tabs, and other similar markdown extensions

Progress so far

Platform	Open source	Navigation	Automatic test	Styling	Analytics	Markdown	Markdown extensions
Plain GitHub Markdown	✅	-	-	-	-	✅	-
AsciiDoctor	✅	some	✅	-	✅	-	-
GitBook	-	✅	-	✅	✅	✅	✅
mdBook	✅	✅	?	✅	?	✅	✅
Material on mkDocs	✅	✅	✅	✅	✅	✅	✅