Re: Important - Documentation Discussion

[Alejandro Vallejo <alejandro.vallejo@cloud.com>]

Hi,

On Wed, Nov 15, 2023 at 11:43:46AM +0000, Kelly Choi wrote:
> Hi all,
> 
> As you may be aware, we are in the process of reviewing our existing
> documentation platform and content. In order to meet the requirements of
> the community and project, I need your input and feedback.
> 
> The aim of the new documentation is to encourage community members to
> collaborate in updating content (where possible) and educate users on how
> the project works. The updated documentation will be hosted on our new
> upcoming website.
> 
> *Suggestion for user-orientated documentation:*
> 
>    - git - for hosting (gitlab recommended)
>    - RST - for the format of the documentation
>    - Sphynx - to generate web pages and PDF and other formats from RST
In my experience Sphinx's strength is in its ability to cross-reference the
code. That isn't something terribly helpful for user documentation, and it
makes the whole thing harder to set up for no clear benefit.

For user-facing docs I'd propose `mkdocs` instead, which is a lot more
focused and simpler to set up (can be done literally in a couple of
minutes). The main difference would be that it takes Markdown rather than
RST[1]. It trivially supports plugins for interesting things, like mermaid
(for sequence/block diagrams or FSMs) 

Main website: https://www.mkdocs.org/
Plugin catalog: https://github.com/mkdocs/catalog
    * mermaid plugin: https://github.com/fralau/mkdocs-mermaid2-plugin
    * kroki plugin: https://kroki.io/

[1] I happen to prefer Markdown, as I find it easier to read and write, but
    that's just personal preference

> 
> *Suggestion for developer reference documentation:*
> 
>    - Doxygen
>    - Kerneldoc
>    - Open to other suggestions here
There's 2 areas here. The format for the annotations, and the visualization
frontend. They need not be the same. Using Doxygen seems the less
"not-invented-here" approach, while kerneldoc would 

As for the frontend I would suggest to _not_ use Doxygen itself as the
generated websites are hideous to look at. Sphinx (through Breathe) or any
other Doxygen-database parse wouldr do the job as well providing a much
(much) better output.

> 
> Example of how documentation will be split:
> 
>    1. Getting started/beginner user guides
>    2. Learning orientated tutorials
>    3. Goal-orientated how-to guides
>    4. Developer related documentation
(1-3) seem like pretty much the same thing. Guides of increasing complexity
meant to train a new user/admin. Dividing such a section in those 3 blocks
seems sensible.

(4) could be split in a "Developer Manual", which would contain plain
explanation for dev-heavy concepts, and a "Reference Manual" with links to
the Doxygen-esque websites and a higher focus on implementation details.

> 
> Side note: Whilst I appreciate everyone has a different vision of what
> ideal documentation looks like, please be mindful that not everyone's
> thought processes or depth of knowledge are the same. All ideas are
> welcome, and decisions made will always reflect community needs.
> 
> Many thanks,
> Kelly Choi
> 
> Open Source Community Manager
> XenServer, Cloud Software Group

Cheers,
Alejandro