<html><body><div style="color:#000; background-color:#fff; font-family:times new roman, new york, times, serif;font-size:12pt"><div><span>I'm also in favour of separating the reference sections from the manual. I imagine this would work like these pages:</span></div><div><span><br></span></div><div><span>Save Options "Reference": <br></span></div><div><span>http://wiki.blender.org/index.php/Doc:2.5/Manual/Interface/Configuration/File</span></div><div><span>Save Options "Manual": <br></span></div><div><span>http://wiki.blender.org/index.php/Doc:2.5/Manual/Vitals/Undo_and_Redo#Save_and_Auto_Save</span></div><div><br><span></span></div><div><span>where the reference page is essentially a glorified index and the manual page goes into more detail and usage cases.</span></div><div><br><span></span></div><div><span>I'm just throwing out ideas here, but the operator cheat sheet available from the Help menu might be a good place to look into in terms of
automating the reference. The cheat sheet lists the available operators and provides a brief description. It might be possible to have the cheat sheet link with the keymap or generate the cheat sheet with some window location info.<br></span></div><div><br><span></span></div><div><span>I'm a fan of automating the reference generation (and making it a priority) as much as possible since doing it manually will be somewhat dull.<br></span></div><div><br></div><div style="font-family: times new roman, new york, times, serif; font-size: 12pt;"><div style="font-family: times new roman, new york, times, serif; font-size: 12pt;"><font face="Arial" size="2"><hr size="1"><b><span style="font-weight:bold;">From:</span></b> mindrones <mindrones@gmail.com><br><b><span style="font-weight: bold;">To:</span></b> Blender Documentation Project <bf-docboard@blender.org><br><b><span style="font-weight: bold;">Sent:</span></b> Sunday, 25 September 2011 8:06
PM<br><b><span style="font-weight: bold;">Subject:</span></b> Re: [Bf-docboard] Wiki upgrade 2011<br></font><br>Hi,<br><br>at the moment we're all recovering a bit after all these months of work<br>on the new wiki :)<br><br>Surely, after a bit of rest we'll concentrate more on the contents, just<br>now exactly now :)<br><br><br>RE: manual structure + pdf<br>------------------------------<br><br>Before we start discussing the structure or the pdf, I'd prefer we<br>concentrate on the long awaited Blender Reference.<br><br>As explained at the Blender Conference 2010 Documentation Roundtable,<br><br><a href="http://download.blender.org/documentation/bc2010/blender_documentation_roundtable.pdf" target="_blank">http://download.blender.org/documentation/bc2010/blender_documentation_roundtable.pdf</a><br><br>we would like to be able to separate the Reference from the Manual.<br><br>Most of the contents in the manual try to explain what a certain command<br>does
or which shortcut you have to press to use it, and that's not<br>something you want to read in a manual.<br><br>Rather, the manual should refer to (or send you to) the reference when<br>it comes to show a command, and concentrate on how to do things in<br>general. It should not explain anything too specific (that's for a<br>tutorial).<br><br>At the conference we did this example: say that you want to document<br>texturing. Then:<br><br>- the Reference should explain:<br> - the various spaces/areas where you find the tools<br> - menus<br> - shortcuts<br><br>- the Manual should explain how to texture simple models (planes,<br> spheres) in order to tell you the basics of the texturing procedure,<br> highlighting problems and caveats in general<br><br>- Tutorials should explain how to texture specific models (say, a face,<br> or sintel's jacket, or a door).<br><br>Manual and Tutorials should not tell you press this and
that or how to<br>select a certain space in Blender, or how to split the window in order<br>to work there. This is something that the reference should do.<br><br>At the moment reference and tutorial contents are quite well mixed in<br>the manual, that is: you find shortcuts in the manual, and how to model<br>a sword as well in the manual, and that's wrong.<br><br>--<br><br>As for shortcuts, rather than use<br><br>"press {{shortcut|w|1}} two times to subdivide the model",<br><br>we should use<br><br>"[[Doc:2.5/Reference/Modeling/Editmode/Subdivide|subdivide]] the model<br>two times",<br><br>and let the user choose if to click on the link to "subdivide": only<br>he/she knows if that information is useful or not to him.<br><br>I'd like that clicking or hovering on the "subdivide" link shows content<br>in the TOC sidebar, if the content is not too big, rather than loading<br>the subdivide reference
page.<br><br>Also,<br><br>Doc:2.5/Reference/Modeling/Editmode/Subdivide<br><br>might be different from<br><br>Doc:2.6/Reference/Modeling/Editmode/Subdivide<br><br>so it's not much convenient to hardcode "{{shortcut|w|1}}" in the<br>wikitext, because it's a nightmare to maintain.<br><br>--<br><br>I'd like to keep manual, tutorials and reference aligned, so that we<br>have for example:<br><br>Doc:2.x/Reference/Modeling/*<br>Doc:2.x/Manual/Modeling/*<br>Doc:2.x/Tutorials/Modeling/*<br><br>hence I'd prefer to discuss the Reference structure first.<br><br><br>The next step is to try to get an automated Reference from Blender's<br>code, so when we get there, hopefully soon, IMHO we can discuss more<br>about the rest. Otherwise we keep doing things manually, which is a<br>massive task, and the wiki team is not large enough to cover well the<br>whole manual/reference IMO :/<br><br><br>I hope this clarifies things a bit :)<br><br><br><br>RE: wiki feature
requests<br>------------------------------<br><br>Please file them at<br><br><a href="http://projects.blender.org/projects/blend-doc/" target="_blank">http://projects.blender.org/projects/blend-doc/</a><br>("Feature Requests" tracker)<br><br>it's easier to keep track :)<br><br><br>Regards,<br>Luca<br><br><br>_____________________________<br><br><a href="http://www.mindrones.com" target="_blank">http://www.mindrones.com</a><br>_______________________________________________<br>Bf-docboard mailing list<br><a ymailto="mailto:Bf-docboard@blender.org" href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br><a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br><br><br></div></div></div></body></html>