Re: Possible changes to the project docs

["Mark Van De Vyver" <mark@taqtiqa.com>]

[-- Attachment #1: Type: text/plain, Size: 2169 bytes --]

Hmm, it seems the interwebs ate my prior message.   TLDR;

Considering AsciiDoc, MkDoc-Materialize, Docusarus, Sphinx and Antora

* A switch from DocBook is a net benefit regardless of what you switch too.
* Making docs more accessible to dev and user contributors is the key.
* I regard ascidoc/md/rst as near enough that they don't swing the decision - in terms of being approachable to devs and users.
* A potential discriminator is l10n/i18n - on the face of it they all seem to be imperfect (wip) and adequate.
* Is there any other strategic benefit to be obtained?

I think so.  Looking at https://antora.org/ this stands out:
*The ability to retrieve and aggregate all the content from different git repositories.*

This provides the following headroom:
* Move documentation into the repo that holds the related code.  Bringing documentation closer to devs who are more likely to write some preliminary documentation and correct documentation errors/ambiguities.
* Allow individual repo's/tools to evolve at their own pace - a release that repo/tool X would like to make 'yesterday' can be made and everyone can be confident the docs are still consistent (assumes that tool/repo-Y does not make any statements about tool/repo-X in the Y-docs)
* Allow the project to treat a repo as a 1st class citizen even if it is not under the openembedded.org or yoctoproject.org
* Corollary: Allow any repo outside of openembedded.org or yoctoproject.org to incorporate whichever of the tools/repos they need (git cloning & forking model allows/encourages that) and present documentation that is integrated and targeted (Antora could - eventually - allow/encourage that).
* Give the Yocto-project flexibility in how to organize itself going forward - documentation is not an impediment.

Of course there is a learning curve and the docs need to be refactored back to their home tool/repo.
To my mind there is a categorical distinction that can be made between the DocBook alternatives.

The questions is whether any of the above conjectures are of value or attractive?

HTH?
--
Kind regards
Mark

Mark Van de Vyver, B.Bus(Hons), PhD(Dist)

[-- Attachment #2: Type: text/html, Size: 2441 bytes --]