Important - Documentation Discussion

[Kelly Choi <kelly.choi@xxxxxxxxx>]

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