[Bf-docboard] Manual Structure project update 2

Wed Aug 2 16:23:30 CEST 2006

Ok!

I'm pretty much done with all the big changes *phew*.

There's a bit of cleanup work to do (straggler template-ifying/moving  
tutorials/writer's guidelines) that I'll try and take care of  
tomorrow, but for the most part, it's pretty complete. Of course the  
wiki isn't (and may never be), so happy writing, all! :)

cheers

Matt

On 02/08/2006, at 14:28 PM, Matt Ebb wrote:

> 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
>
>
>
> _______________________________________________
> 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/20060803/fe10d87e/attachment.html