[Bf-docboard] Manual scope

Mon Jan 26 02:43:43 CET 2015

On Mon, Jan 26, 2015 at 12:04 AM, Pep Ribal <pepribal at gmail.com> wrote:
> I completely understand your point. There are 2 possible approaches:
>
> 1. Hey, let's do this. Whoever can do anything, just go for it.
> 2. Let's apply Project Management techniques to get it done.
>
> Option 1 is what it has been around for years and years.
>
> Option 2 is all about breaking down the job into tasks and assign deadlines
> to those. If you have the necessary degree of commitment, perhaps you won't
> meet the deadline, but you'll end up doing the task. If you don't have a
> deadline and don't have that degree of commitment, you will do the task
> tomorrow. And tomorrow never comes. So it's not about deadlines. It's about
> commitment.
>
> And as I have already said, you have to help people feel commited. Assigning
> tasks and building a real team definitely adds that commitment.
>
> Regarding decisions, if you realize, there are still conversations about
> what should the manual be, what structure should have. After how many years?
> You don't think that a formal decision-making process should be established?

The move to the new manual system has been to impliment the second
option (as you put it).

Regarding formal decission making process - Yes, this is needed,

We could work on the current manual, as a reference manual, after a
month or so, active contributors can have a more formal role in the
decission making process.

> However, I could be wrong, of course.
>
> Regards,
>
> Pep.
>
>
> 2015-01-25 20:00 GMT+08:00 Gaia <gaia.clary at machinimatrix.org>:
>>
>> #################
>>   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).
>>
>> 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 :)
>>
>> #############################
>>   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.
>>
>> 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
>>
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>

-- 
- Campbell