[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Important - Documentation Discussion
Hi all,
After gathering different feedback from members of the community, please see below.
We will be moving ahead with Git + RST + Sphinx + Kroki as the new platforms for user documentation.
Many of you have specified you don't necessarily have a preference for the platform, but instead a need for updated content.
Anticipated next steps: - Begin scoping how documentation will be split out (e.g. getting started/tutorials/how-tos)
- Building out the new documentation platform
- Migrate the existing/relevant content over to the new platform
- Commit changes in Git
- Use Sphinx to generate HTML or other formats needed from RST files
- Align this to be launched on our new Xen Project webpage. (We may have the existing content visible whilst we work on revamping the documentation.)
- Create smaller working groups to update and plan documentation, and update these periodically, before pushing to the new webpage.
This will be a joint effort within the community, and I am hoping to count on our members to facilitate these changes. I'll be asking everyone for their help, but if you'd like to volunteer on any of the specific steps, please let me know. The smaller working groups are likely to split into teams concerning the subprojects, but this is open for discussion.
Many thanks, Kelly Choi
Xen Project Community Manager XenServer, Cloud Software Group 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
|
