[Bf-docboard] Manual scope

Wed Jan 28 12:31:01 CET 2015

>From the replies here and talking with Greg & Ton,
no real objections were raised.

So we'll make some changes to make it clear this is a reference manual.

- Change the title.
- Include text in the *Writing Style* section about the goals of the manual.
- Remove some tutorial style sections (though there aren't many of
them). Some can just be modified to explain common usage, without
removing the content too.

On Mon, Jan 26, 2015 at 2:45 PM, Campbell Barton <ideasman42 at gmail.com> wrote:
> On Sun, Jan 25, 2015 at 11:00 PM, Gaia <gaia.clary at machinimatrix.org> wrote:
>> #################
>>   3 Questions...
>> #################
>>
>> come into my mind every time when i work on the manual pages:
>>
>> - Who is the intended audience?
>> - What is the anticipated content?
>> - How is the manual meant to be used?
>>
>> Here is what i believe (please correct me if i am wrong):
>>
>> - intended audience: Everybody who USES Blender as a tool.
>> - anticipated content: Everything that is need to USE Blender.
>> - document usage: can't tell in general (but see below).
>>
>> ############################
>>   How our Addon Users do it
>> ############################
>>
>> Now here is how the users of our own (third party-) Blender-Addon
>> typically behave:
>>
>> 1.) user does experiments (without reading the docs).
>> 2.) user has an issue.
>> 3.) user tries to solve that particular issue.
>> 4.) user continues at 1.
>>
>> user can be an expert or a noob, the questions are different,
>> the approach to find a solution for a particular issue seems similar:
>>
>> - Google solution.
>> - Watch youtube videos.
>> - Ask in chat and or forums.
>> - Use blender.stackexchange (recently became very popular).
>> - Look at the blender manual (seems unpopular).
>>
>>
>> ####################################
>>   My personal goal and wishlist ...
>> ####################################
>>
>> I personally would like to see the documentation getting
>> more useful (more reliable, more up to date) and thus
>> also more popular. This would help us to reduce the
>> tremendous amount of questions (in our community)
>> about the (basic) usage of Blender.
>>
>> For the documentation my wishlist is:
>>
>> - Can be searched by keywords.
>> - Can be browsed with few clicks.
>> - Can be understood by artists.
>> - Is complete but also brief (no walls of text).
>> - Is referenced from Blender itself (RMB -> Onlinemanual).
>
> +1! all good goals for a reference manual.
>
>> I personally do not care if this is called Manual or Reference.
>> However i am a big fan of easy to use and concise documentation.
>> Hence i try to write with that in mind :)
>
> Its an important distinction for both authors and to set user expectations,
>
> The main point being - do we include step-by-step instructions of how
> to make things in blender (tutorials).
>
>
>> #############################
>>   The documentation Team ...
>> #############################
>>
>> Honestly i believe that what is needed is people who
>> do the documentation and not so much people who make
>> decisions, assignments and deadlines.
>
> Well we need both, but we need people who write docs and understand
> whats involved to be working on them.
> Who can then make good decissions about what to do.
>
>> I personally would bail out immediately when someone
>> told me to improve a particular document and deliver
>> withing 2 weeks.
>>
>> -gaia-
>>
>> On 25.01.2015 11:44, Pep Ribal wrote:
>>
>> I explained my view on the subject a few days ago. To summarize:
>>
>> -There should be both a manual AND a reference.
>> -Manual sections should be pretty much the same there are now (modeling,
>> rendering, rigging, animation,...)
>> -Reference sections should be broken, into editors.
>> -Manual can then link to information in the reference.
>> -The current "editors" section in the manual doesn't make any sense, as this
>> is exactly the Blender reference.
>>
>> I emphasize the need to set up a team asap, and start meetings and
>> decisions, assignments and deadlines. Otherwise, I feel the blender
>> documentation discussion as a chronic incurable disease.
>>
>> I'm not just pointing out what you should do. I'm also offering my help in
>> whatever you need.
>>
>> Regards.
>>
>> Pep.
>>
>>
>> 2015-01-25 4:03 GMT+08:00 Wim Teuling <wfteuling at yahoo.com>:
>>>
>>> A reference manual is a great idea: every other manual I read or worked
>>> with is exactly that: a place to quickly find information how to use a
>>> particular tool. No fluff, and focused. Once users know the terminology and
>>> basic usage principles, this should enable them to look for tutorials.
>>>
>>> A reference manual, however, requires an solid and robust structure, and
>>> should offer a good search function. This is currently not the case with
>>> Blender's manual, or at least only partly true, unfortunately.
>>>
>>> A basic search for "selection", or "selection methods" results in a
>>> useless search result. Trying to find "selection" as a category in the
>>> current manual structure yields nothing! I would expect that to be part of
>>> "Basics" under "Getting Started".
>>>
>>>
>>>
>>>
>>> On Saturday, January 24, 2015 5:20 AM, Greg Zaal <gregzzmail at gmail.com>
>>> wrote:
>>>
>>>
>>>
>>> I'd agree - a reference manual seems like a much more easily reached
>>> target. I myself would prefer to have a good reference available than a
>>> guided manual.
>>>
>>> It would definitely make maintenance simpler, and would be easier to write
>>> since it requires less teaching and language skills than a guided manual.
>>>
>>> If people still wish to write tutorials and in-depth examples, these can
>>> be done elsewhere (personal wiki pages, forums, blogs, etc) and linked to
>>> from the manual. This is already done occasionally, for example the array
>>> modifier (http://blender.org/manual/modifiers/generate/array.html#tutorials)
>>> links to some external resources.
>>>
>>> On 24 January 2015 at 08:56, Campbell Barton <ideasman42 at gmail.com> wrote:
>>>
>>> It was suggested by @el_diablo that we might consider restricting the
>>> manual to being a reference manual.
>>>
>>> see:
>>>
>>> http://blenderartists.org/forum/showthread.php?360263-Blender-User-Manual-Official-Call-for-Help!&p=2803818&viewfull=1#post2803818
>>>
>>> This doesn't mean we have to make this simply lists of button
>>> descriptions, we should still make this text for users and give some
>>> guidance (usage info and tips).
>>>
>>> Examples of pages I'd consider reasonable for a 'reference manual'
>>>
>>> -
>>> https://www.blender.org/manual/modeling/meshes/editing/subdividing/knife_subdivide.html
>>> - https://www.blender.org/manual/modifiers/generate/solidify.html
>>> -
>>> https://www.blender.org/manual/getting_started/basics/interface/buttons_and_controls.html
>>>
>>> This means we wouldn't attempt anything like tutorials or howto's.
>>>
>>> The main reasons I suggest this is...
>>>
>>> - So far we only have a small group of active writers.
>>> - This is what the manual is for the mostpart anyway.
>>> - The few tutorials from the wiki were OK (at best),
>>> ... Youtube, blender.stackexchange & dedicated tutorial sites are far
>>> better suited to helping users with spesific interests.
>>> - This is something developers can keep up tp date when functionality
>>> is changed, without giving us pages of text to maintain.
>>>
>>> --
>>> - Campbell
>>> _______________________________________________
>>> Bf-docboard mailing list
>>> Bf-docboard at blender.org
>>> http://lists.blender.org/mailman/listinfo/bf-docboard
>>>
>>>
>>>
>>> _______________________________________________
>>> Bf-docboard mailing list
>>> Bf-docboard at blender.org
>>> http://lists.blender.org/mailman/listinfo/bf-docboard
>>>
>>>
>>>
>>> _______________________________________________
>>> Bf-docboard mailing list
>>> Bf-docboard at blender.org
>>> http://lists.blender.org/mailman/listinfo/bf-docboard
>>>
>>
>>
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-docboard
>>
>>
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-docboard
>>
>
>
>
> --
> - Campbell

-- 
- Campbell