[Bf-docboard] Bf-docboard Digest, Vol 51, Issue 15

[Chris R. -- Spectre-7]

Howdy Roger/Papa!

I don't want to sound ungrateful and I apologize if my tone was abrasive.  Let me start off by saying thank you for the work you've done on those sections, not to mention the help you've given me over the years in the forums.  I really appreciate your efforts, and I very likely wouldn't be here mucking around with this stuff at all without them.

Now, I absolutely agree that there should be a section for each shader, and visual examples are an excellent and useful addition.  My issue is with the specific visual examples produced.

In most of the diffuse examples, the settings for the diffuse shader itself remain unchanged while the specular shader has been adjusted.  This strikes me as unnecessarily confusing, especially to new users who aren't yet likely to be comfortable with the difference between the two shader classes.   It seems an odd decision when you could have easily disabled specular shading altogether.

I've already produced a series of potential replacement images which I believe more clearly illustrate the properties of the diffuse shaders.  My Minnaert example can be seen here: http://sites.google.com/site/spectre7/Home/Manual-Shaders-Minnaert2.png

Compare to the current example here: http://wiki.blender.org/index.php/Image:Manual-Shaders-Minnaert.png

My goal in producing these images was to demonstrate each shader's settings as clearly and effectively as possible, and I think I've largely succeeded in that task.

Concerning the usage of the wiki discussion pages, I entirely understand how small things like that can slip through the cracks.  My experience with other wikis led me to assume that a page's discussion area would be the proper place to suggest changes, and the current <a href='http://wiki.blender.org/index.php/Meta:Guides/Writer_Guide'>writer's guide</a> would seem to reinforce that.  If this is not the currently prescribed procedure, it would be very helpful to update the guidelines to reflect those changes.

On to the matter of polish versus new content.  While I fully appreciate the lack of resources available around these parts, I'd point out that Blender has a very swift development cycle.  New features are always being added and old features are frequently in flux, so as long as polish remains the third priority, polish will simply never happen.

That's really unfortunate.

I think we can all agree that of Blender's many virtues, pick-up-and-play ease-of-use isn't among them.  Blender is daunting and disorienting to a new user, and the manual becomes an indispensable part of the new user experience because of it.

For this reason, the manual's quality level should be a key consideration.  It can mean the difference between someone turning away in frustration or potentially becoming a life-long user and advocate.  A manual also partially functions as the program's outward face, affecting how Blender and its community are perceived.  Documentation that looks cobbled together and rough around the edges will imply that Blender is cobbled together and rough around the edges, and I don't think that's the image anybody wants to portray.

The release of version 2.5 is looming out on the horizon, and we can very likely expect a large influx of new users when it hits.  I believe it's imperative that the documentation be in a highly polished and publishable state before that happens.  I would personally like it to be a shiny, glittering gem. :)

To that end, I intend to go through the entire manual with a fine-toothed comb; the Materials section was basically chosen as a test case.  My main priorities are to make every section informative, clear and consistent, and I'm convinced that the manual will benefit greatly from this sort of attention.

Finally, concerning the Lambert shader description I quoted, I have no problems at all with the use of humor.  In fact, I'm a fan of Scott Kelby's work (see his excellent The Digital Photography Book), which is both highly informative and funny as heck.  

My issues are that the shader description is not very informative, nor is it grammatically well formed.  The grammar problem has nothing to do with the humor; the sentence is just missing an article.

"This is Blender's default diffuse shader, and is good general all-around work horse...neigh!"

Should be:

"This is Blender's default diffuse shader, and is *a* good general all-around work horse...neigh!"

These types of small errors plague the manual at present, and are exactly the sort of thing I'd like to ferret out.

Apologies for the length. :)

Cheers,
Chris J. Randolph (Spectre-7)

"The most merciful thing in the world, I think, is the inability of the human mind to correlate all its contents." - Howard Phillips Lovecraft

_________________________________________________________________
Windows Live™ Hotmail®:…more than just e-mail.
http://windowslive.com/online/hotmail?ocid=TXT_TAGLM_WL_HM_more_042009
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20090430/7b0b7a9f/attachment.htm