[Bf-docboard] Manual Structure project update 2
Matt Ebb
matt at mke3.net
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
More information about the Bf-docboard
mailing list