[Bf-docboard] Manual Structure project finished - request for template trans

Fri Aug 4 17:48:11 CEST 2006

Great work, Matt! This was a much needed project.
=====================
From: Matt Ebb <matt at mke3.net>
Date: 2006/08/04 Fri AM 06:41:04 CDT
To: Blender Documentation Project <bf-docboard at projects.blender.org>
Subject: [Bf-docboard] Manual Structure project finished - request for	template translation!

<HTML><BODY style="word-wrap: break-word; -khtml-nbsp-mode: space; -khtml-line-break: after-white-space; ">Although there are few loose ends, I'm calling this project complete. Some articles I haven't touched, since they were so misleadingly out of date it wasn't worth the time, but for the most part things should be spick and span and anything that I find left over, I'll continue to fix up along the way.<DIV><BR class="khtml-block-placeholder"></DIV><DIV>Today I added info on the reference template to the style guide ( <A href="http://mediawiki.blender.org/index.php/Meta/Style_Guide">http://mediawiki.blender.org/index.php/Meta/Style_Guide</A> ) and the templates page ( <A href="http://mediawiki.blender.org/index.php/Meta/Templates">http://mediawiki.blender.org/index.php/Meta/Templates</A> ).<DIV><BR class="khtml-block-placeholder"></DIV><DIV>There's one more thing that I could use a hand with though. I originally built into the reference template the ability to use different languages! This means that, for example, the template can be used on a Japanese language page and instead of the template saying "Menu" in the box it will say "&#12513;&#12491;&#12517;&#12540;", and so on for the other languages, which is of course much nicer. Writers just need to pass in the two-letter language code that they want to use, instead of "en" when they call the template.</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>Now it just needs the translations. The only language other than English that I know anything much of is Japanese, so even though we have no Japanese pages, I've edited the RefBox template ( <A href="http://mediawiki.blender.org/index.php?title=Template:RefBox">http://mediawiki.blender.org/index.php?title=Template:RefBox</A> ) with example text in Japanese to show how to add a translation. It's quite simple - when you edit the page, it's just a matter of copying the "| ja=&#12513;&#12491;&#12517;&#12540;" lines and pasting them underneath with the new language.</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>If any of you that speak languages other than English can help out editing the template translating these, it would be great! I'm happy to help or answer any questions about it too.</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>Thanks very much!</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>Matt</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV><BR><DIV><DIV>On 03/08/2006, at 00:23 AM, Matt Ebb wrote:</DIV><BR class="Apple-interchange-newline"><BLOCKQUOTE type="cite">Ok!<DIV><BR class="khtml-block-placeholder"></DIV><DIV>I'm pretty much done with all the big changes *phew*.</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>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! :)</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>cheers</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>Matt</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV><BR><DIV><DIV>On 02/08/2006, at 14:28 PM, Matt Ebb wrote:</DIV><BR class="Apple-interchange-newline"><BLOCKQUOTE type="cite">Thanks! No other feedback, so I'm going to go ahead right now :) Will mail again when it's finished.<DIV><BR class="khtml-block-placeholder"></DIV><DIV>Have fun at siggraph!</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV>Matt</DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV><BR class="khtml-block-placeholder"></DIV><DIV><BR><DIV><DIV>On 29/07/2006, at 10:52 AM, Will DeVore wrote:</DIV><BR class="Apple-interchange-newline"><BLOCKQUOTE type="cite"><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Hey Matt,</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">IMHO, I think you are doing a great service to the docs.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">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.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">I look forward to picking back-up when your project and the other BSoDs are completed.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">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.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Just food for thought....</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Off to Siggraph now. ;P</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">-Will</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Matt Ebb wrote:</DIV> <BLOCKQUOTE type="cite"><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Hi all,</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">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.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">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 (<A href="http://mediawiki.blender.org/index.php/User:Broken/ReferenceBoxGuidelines">http://mediawiki.blender.org/index.php/User:Broken/ReferenceBoxGuidelines</A>) - 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.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">The next bit remaining in the project in my proposal ( <A href="http://mediawiki.blender.org/index.php/User:Broken/SummerOfDocs2006Restructure">http://mediawiki.blender.org/index.php/User:Broken/SummerOfDocs2006Restructure</A> ) 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.<SPAN class="Apple-converted-space"> </SPAN></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">I've given it some thought, referenced the old discussions and have written a proposed, comprehensive TOC here: <A href="http://mediawiki.blender.org/index.php/User:Broken/ManualTOC">http://mediawiki.blender.org/index.php/User:Broken/ManualTOC</A> . 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:</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">* 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.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">* I've tweaked some names, and removed all the "/PartIII/" etc. designators from the page titles, for a few reasons.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>a) They're unnecessary - who cares if it's part 5 or 6, the content is what counts</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>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</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>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).</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><SPAN class="Apple-converted-space"> </SPAN>(btw, the black text in parentheses is for description now, and won't stay).</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">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.</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">cheers</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Matt</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; "><BR></DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">------------------------------------------</DIV><DIV style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; ">Matt Ebb • <A href="mailto:matt at mke3.net">matt at mke3.net</A> • <A href="http://mke3.net">http://mke3.net</A></DIV></BLOCKQUOTE></BLOCKQUOTE></DIV></DIV></BLOCKQUOTE></DIV></DIV></BLOCKQUOTE></DIV><BR><DIV> <SPAN class="Apple-style-span" style="border-collapse: separate; border-spacing: 0px 0px; color: rgb(0, 0, 0); font-family: Lucida Grande; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; text-align: auto; -khtml-text-decorations-in-effect: none; text-indent: 0px; -apple-text-size-adjust: auto; text-transform: none; orphans: 2; white-space: normal; widows: 2; word-spacing: 0px; "><SPAN class="Apple-style-span" style="border-collapse: separate; border-spacing: 0px 0px; color: rgb(0, 0, 0); font-family: Lucida Grande; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; text-align: auto; -khtml-text-decorations-in-effect: none; text-indent: 0px; -apple-text-size-adjust: auto; text-transform: none; orphans: 2; white-space: normal; widows: 2; word-spacing: 0px; "><DIV>------------------------------------------</DIV><DIV>Matt Ebb • matt at mke3.net • <A href="http://mke3.net">http://mke3.net</A></DIV><DIV><BR class="khtml-block-placeholder"></DIV><BR class="Apple-interchange-newline"></SPAN></SPAN> </DIV><BR></DIV></DIV></BODY></HTML>

_______________________________________________
Bf-docboard mailing list
Bf-docboard at projects.blender.org
http://projects.blender.org/mailman/listinfo/bf-docboard