<html><head><style>body{font-family:Helvetica,Arial;font-size:13px}</style></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div id="bloop_customfont" style="font-family:Helvetica,Arial;font-size:13px; color: rgba(0,0,0,1.0); margin: 0px; line-height: auto;"><div id="bloop_customfont" style="margin: 0px;">Hello everybody,</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">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).</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">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.</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">Wikis are really good for having many interlinking pages (like Wikipedia), but less will suited for managing a structured document</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">Pros:</div><div id="bloop_customfont" style="margin: 0px;">- Documentation can be edited and updated locally (no need to edit online as with a wiki).</div><div id="bloop_customfont" style="margin: 0px;">- Documentation can be output to various formats, HTML, PDF & EPUB.</div><div id="bloop_customfont" style="margin: 0px;">- Documentation can be downloaded locally by users or even included with Blender releases.</div><div id="bloop_customfont" style="margin: 0px;">- The manual can be versioned (currently the Wiki has problems with documentation for different Blender versions).</div><div id="bloop_customfont" style="margin: 0px;">- The manual organization can be managed more easily in terms of the overall structure.</div><div id="bloop_customfont" style="margin: 0px;">- RestructuredText can be parsed by Python for creating better tools to automatically manage/validate docs.</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">Cons:</div><div id="bloop_customfont" style="margin: 0px;">- Some people may prefer MediaWiki since its well known.</div><div id="bloop_customfont" style="margin: 0px;">- No integrated online editing capability.</div><div id="bloop_customfont" style="margin: 0px;"> </div><div id="bloop_customfont" style="margin: 0px;">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. </div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">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].</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">Some maintenance is planned on the existing MediaWiki system as well. In particular we would like to:</div><div id="bloop_customfont" style="margin: 0px;">- Update or replace the current Naiad theme (not working well on mobile)</div><div id="bloop_customfont" style="margin: 0px;">- Attempt to fix the NavTree (always broken due to caching)</div><div id="bloop_customfont" style="margin: 0px;">- Update the MediaWiki software</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">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.</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">Feedback on this proposal is very much appreciated at this point.</div><div id="bloop_customfont" style="margin: 0px;"><br></div><div id="bloop_customfont" style="margin: 0px;">Thanks,</div><div id="bloop_customfont" style="margin: 0px;">Campbell Barton and Francesco Siddi </div><div id="bloop_customfont" style="margin: 0px;"><br></div></div></body></html>