[Bf-docboard] Documentation status and upgrade proposal

[Francesco Siddi]

Hello everybody,

after some conversations about how to improve Blender's documentation system, we have worked out a proposal to migrate the Blender User Manual to Sphinx (the same documentation system currently used for Blender's API).

Blender’s Wiki manual is not evenly maintained, while a new technology doesn’t solve the problem of writing a manual, it may help us to better maintain an important document.

Wikis are really good for having many interlinking pages (like Wikipedia), but less will suited for managing a structured document

Pros:
- Documentation can be edited and updated locally (no need to edit online as with a wiki).
- Documentation can be output to various formats, HTML, PDF & EPUB.
- Documentation can be downloaded locally by users or even included with Blender releases.
- The manual can be versioned (currently the Wiki has problems with documentation for different Blender versions).
- The manual organization can be managed more easily in terms of the overall structure.
- RestructuredText can be parsed by Python for creating better tools to automatically manage/validate docs.

Cons:
- Some people may prefer MediaWiki since its well known.
- No integrated online editing capability.
 
Managing images via GIT is one if a weaknesses in the proposal, so we will keep open the option to store them outside of GIT (use SVN as we do for Blender libs), or create new git repos for major Blender version changes to avoid the burden of binary files becoming too much over time. 

You can find more details about this proposal here [http://www.graphicall.org/ftp/ideasman42/html/readme.html], and you can see a working prototype with Cycles documentation [http://www.graphicall.org/ftp/ideasman42/html/cycles_rendering/index.html].

Some maintenance is planned on the existing MediaWiki system as well. In particular we would like to:
- Update or replace the current Naiad theme (not working well on mobile)
- Attempt to fix the NavTree (always broken due to caching)
- Update the MediaWiki software

If the user documentation proposal is successful, wiki.blender.org, will keep hosting all development documents and material that does not fit the user manual.

Feedback on this proposal is very much appreciated at this point.

Thanks,
Campbell Barton and Francesco Siddi 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20140506/68a4a9b9/attachment.htm