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: 1. Begin scoping how documentation will be split out (e.g. getting started/tutorials/how-tos) 2. Building out the new documentation platform 3. Migrate the existing/relevant content over to the new platform 4. Commit changes in Git 5. Use Sphinx to generate HTML or other formats needed from RST files 6. 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.) 7. 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 On Fri, Nov 17, 2023 at 1:58 PM Kelly Choi <kelly.c...@cloud.com> wrote: > 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 > > > On Wed, Nov 15, 2023 at 12:16 PM Alejandro Vallejo < > alejandro.vall...@cloud.com> wrote: > >> 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 >> >
