Important - Documentation Discussion

Important - Documentation Discussion

[Kelly Choi]

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

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

*Suggestion for developer reference documentation:*

   - Doxygen
   - Kerneldoc
   - Open to other suggestions here

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

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

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

Re: Important - Documentation Discussion

[Alejandro Vallejo]

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

Re: Important - Documentation Discussion

[Kelly Choi]

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

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.vallejo@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
>

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

Re: Important - Documentation Discussion

[Kelly Choi]

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

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.choi@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.vallejo@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
>>
>

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