[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Important - Documentation Discussion
Hey Alejandro,
Thanks for your feedback. I'll consider all your points, and any other comments from the community before proceeding on the next steps.
If anyone else has any further ideas, please let me know Friday 24th November 2023.
Many thanks, Kelly Choi
Open Source Community Manager XenServer, Cloud Software Group
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
|
