Technical documentation tooling

[aoudiamoncef]

Actually, we are using reStructuredText files which did the trick but IMHO, it's less featured than other solutions.

I explored different types of technical documentation languages in terme of features and tooling. I found that Asciidoc is the most powerful. I use It even for my personal blog and It's widely used for writing technical books.

I tested : markdown with extensions, Latex*, Asciidoc and reStructuredText.

Example : We have to include a TOML file and render It in our documentation... I found no way to do this except in Asciidoc.

.Node base configuration 
[source,toml]
----
include::massa$config.toml[]
----

Asciidoc is widely used, well documented and GitHub have a native support for rendering Asciidoc files.

Asciidoc cheatsheet

[qdrn]

At some point the documentation was on Github with MD/Asciidoc format. The issue is that Github wiki is not really convenient to browse a documentation. We can use another solution than Read The Doc but it's something that takes time. Let's make sure it's really worth it before doing it. What would you suggest ?

[aoudiamoncef]

For sure, it'll take time to convert current documentation to Asciidoc, but if it could give us a bunch of features and a friendly syntaxe, so we should think about it.

It's not a big deal to add some attractive HTML/CSS/JS output for Asciidoc files using Jekyll or Hugo.

We could reuse what I've done to build my personal blog which uses Asciidoc + Hugo

Jekyll vs Hugo

Jekyll doc themes

Hugo doc themes

Static website generators

[aoudiamoncef]

@damip It could be interesting to create a new repository called for example doc.massa.com. We'll have a complete CI/CD workflow which is not related to Massa main project lifecycle

For hosting part, IMHO CloudFlare pages are the best free option.

Github Pages vs CloudFlare pages

[qdrn]

gitbook also seems to be accepting Asciidoc. I like it from a UX/UI perspective. If that suits everyone we could use it.

[aoudiamoncef]

It's a good solution but it's quite expensive. Please see pricing section.

[qdrn]

There's also a free plan. Do we need the features that are not free ?

[aoudiamoncef]

I think that we don't fit the criteria to get free plan

[qdrn]

We could once we are open-source. In any case, I was talking about the https://docs.gitbook.com/pricing/plans#personal-plan.

[qdrn]

I agree that it would be nice to be able to directly add files in our documentation. Are there any other benefits to switching the doc ? (I think we could use a custom domain for RTD).

For me the main priority is adding content to the doc, improving it, etc...

[aoudiamoncef]

I tried to render some existing TOMLs files and I didn't find a way to do it. This is the main reason for opening this issue.

It was a little bit tricky to do because I got an issue with my asciidoctor install on Ubuntu, but the result is satisfying :

I used Hugo + Learn Hugo theme(i18n) + Asciidoc

TODO :

• Fix some CSS issues with Asciidoc rendering.
• Migrate current documentation automatically with Pandoc
• fix conversion errors.
• Render all default configurations files (TOMLs)
• Render different types of diagrams(Mermaid, PlantUML...)
• Add raw html, css and js if needed.
• Complete CI/CD workflow with Github pages + CloudFlare pages.

[aoudiamoncef]

@qdrn I'll keep this project in standby in case we need it in the future. Actually, there is others important priorities for Massa team.