[Bf-docboard] Manual Structure project update 2

[Matt Ebb]

Thanks! No other feedback, so I'm going to go ahead right now :) Will  
mail again when it's finished.

Have fun at siggraph!

Matt



On 29/07/2006, at 10:52 AM, Will DeVore wrote:

> Hey Matt,
>
> IMHO, I think you are doing a great service to the docs.
>
> I like the idea of splitting off the tutorials and your proposed  
> restructure looks good. The BoxGuidelines template looks easy to  
> deal with. I also agree with the removal of the page title  
> designators.
>
> I look forward to picking back-up when your project and the other  
> BSoDs are completed.
>
> Have you thought about how to handle versions between Blender.  
> Sometimes Blender changes quite drastically. What about having some  
> sort of filter that kinda morphs the document according to the  
> version of Blender you are interested. I think of it much like CSS  
> for web pages. Perhaps there could be a list box or something at  
> the top for choosing the version where certain sections may appear  
> or disappear or may even change. We could use templates to control  
> what docs go with which versions.
>
> Just food for thought....
>
> Off to Siggraph now. ;P
>
> -Will
>
> Matt Ebb wrote:
>> Hi all,
>>
>> You may remember me posting about a project I've been working on  
>> alongside the BSoD, to improve the information design and  
>> structure of the reference manual. You can probably find previous  
>> emails in the archives.
>>
>> Anyway, I've *finally* just about finished the enormous task of  
>> updating the various manual pages in the manual to use the  
>> consistent reference information template (http:// 
>> mediawiki.blender.org/index.php/User:Broken/ 
>> ReferenceBoxGuidelines) - there are a couple that haven't been  
>> converted yet, I'm waiting for the next stage of this project. Im  
>> already very happy with the results so far, things look a lot  
>> clearer and nicer.
>>
>> The next bit remaining in the project in my proposal ( http:// 
>> mediawiki.blender.org/index.php/User:Broken/ 
>> SummerOfDocs2006Restructure ) is tweaking the higher level  
>> structure of the manual, and splitting off the tutorials into a  
>> revamped tutorial section. I decided to wait until I'd been  
>> through all the manual pages already to do this, since now after  
>> reading and editing just about every page, I have a very good  
>> understanding of the state of the manual, what is missing, and  
>> what should be tweaked.
>> I've given it some thought, referenced the old discussions and  
>> have written a proposed, comprehensive TOC here: http:// 
>> mediawiki.blender.org/index.php/User:Broken/ManualTOC . The idea  
>> is to have another tutorials TOC with top level containers that  
>> mirror those in the reference manual, both crosslinked (as you can  
>> see in my page). This keeps the reference manual clean and  
>> focused, but also allows nice cross-referencing. Notable  
>> differences between my TOC and the current one are:
>>
>> * I've included yet-to-be-written placeholder titles based on  
>> information I found was missing from the manual. Some of them  
>> (such as node docs) are already elsewhere on the wiki and just  
>> need to be copied over & consistent-ified. I also think it's  
>> worthwhile to keep placeholders on the TOC page, since although it  
>> looks less 'professional' (the manual is hardly at a professional  
>> level now anyway), it shows people what needs to be written, and  
>> encourages contribution there.
>>
>> * I've tweaked some names, and removed all the "/PartIII/" etc.  
>> designators from the page titles, for a few reasons.
>>  a) They're unnecessary - who cares if it's part 5 or 6, the  
>> content is what counts
>>  b) It makes it harder to crosslink to other pages, instead of  
>> just intuitively writing [[Manual/Subsurf]] if I want to link to  
>> the subsurf page, I have to go and hunt down the section number  
>> too in order to make my link
>>  c) It makes the ordering of chapters inflexible, since it means  
>> all new chapters (such as one on compositing) have to be added at  
>> the end of the manual, to prevent changing all the links around.  
>> I'm happy to take care of moving current pages to the new titles,  
>> without '/Part/' (with auto link redirection of course).
>>  (btw, the black text in parentheses is for description now, and  
>> won't stay).
>>
>> So anyway, I thought I'd put this up for comments for a couple of  
>> days, and then go ahead and finish the job! Let me know what you  
>> think.
>>
>> cheers
>>
>> Matt
>>
>>
>> ------------------------------------------
>> Matt Ebb • matt at mke3.net • http://mke3.net
>>
>>
>>
>> --------------------------------------------------------------------- 
>> ---
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at projects.blender.org
>> http://projects.blender.org/mailman/listinfo/bf-docboard
>>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at projects.blender.org
> http://projects.blender.org/mailman/listinfo/bf-docboard

------------------------------------------
Matt Ebb • matt at mke3.net • http://mke3.net



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.blender.org/pipermail/bf-docboard/attachments/20060802/c0fa2a15/attachment.htm