[Bf-docboard] Wiki overhaul discussion; was Bf-docboard Digest, Vol 44, Issue 4

[kamalx]

Roger Wickes wrote:
> Hi everyone! I just got the digest, and am glad to see some interst, 
> so I thought I would add my $0.02 to direct some effort.
> Regarding:
>
> > For myself I've always felt that the documentation should have many
> > parts (books):
> > - one for quick reference where an experimented artist could find a
> > precise description of the use of every feature ;
> > - a manual that would elaborate on the reference to make every sticky
> > point clear, give clear examples where needed and cross-reference to
> > the rest of the Wiki;
> > - a collection of tutorials that would go further than the basics, not
> > just repeat in an informal way what can already be found in the
> > reference or the manual.
>
> There ARE three books:
> wiki.Blender.org/Manual - descriptive, end-user, elaborate
> wiki.Blender.org/Reference - specific, precise, detail
> wiki.Blender.org/Tutorials - workflow, start-to-finish, step-by-step 
> accomplishment-oriented
>
err.. all the three above urls gave me a 404 error at the time of 
writing this. (1556 hrs GMT)

However, even if, say, for the manual, the three versions do exist, 
wouldn't it make sense to update a single document
with new-coming versions of Blender rather than updating all separate 
versions. Please consider the idea of mark-up
for selective content to be shown as mentioned in my other post. I 
strongly feel it would improve maintainability.
> Each book is structured at a high level the same for consistency. So, 
> if I want to know what Blender can do regarding Materials, I flip to 
> the Manual book, Materials section. If I want to know what a specific 
> panel control is/does and maybe the math behind it, I flip to the 
> Reference book, Materials panels. If I am completely lost regarding 
> how to color my cube, I read a Tutorial book Materials section.
>
> All wiki books are listed on wiki.Blender.org, so..maybe you want us 
> to say what I just said on that page, or provide a "Guide to using the 
> Blender Wiki Books" page?
>
> The list of Manual pages that need updating, for those new to the doco 
> effort and want to help, is also ont he wiki.Blender.org page, but is 
> specifically http://wiki.blender.org/index.php/Wiki_Taskswhich i keep 
> updated for each Blender release for changes needed to the Manual 
> book. If someone else wants to augment that page with deficiencies in 
> the other books, go for it. Of course, if anyone sees any issues with 
> any Manual page, please update that to-do list!
>
>
> > - ideally we would have our own introduction to 3D graphics, animation
> > and real-time because not everyone has a mastery of the lingo in use
> > among 3D artists. I guess that I am dreaming...
>
> You are dreaming if you are expecting our intro to 3D graphics, 
> animation and real-time book to be available free of charge. There are 
> entire sets of books in libraries that cover those topics most 
> completely, or available from Amazon, or schools (Animation Mentor) 
> and various web sites that provide very useful information, including 
> some threads in BlenderArtists. Previous/current wiki attempts are 
> marginal at best. With our limited resources, we need to keep Blender 
> documentation focused on using Blender specifically. (Scope Control!) 
> and try to keep the three books up to date: Manual, Reference, Tutorials.
>
:) No doubt scope control is essential but some contextual scoops should 
do no harm though! :P
They're really interesting read within manuals.
> ------------------------------------------------------------------------
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>