[Bf-docboard] Manual scope

[Campbell Barton]

On Sun, Jan 25, 2015 at 9:44 PM, Pep Ribal <pepribal at gmail.com> wrote:
> I explained my view on the subject a few days ago. To summarize:
>
> -There should be both a manual AND a reference.

Perhaps we have different definitions of **reference**.
But I think a well written reference manual, (which isnt just listing
of tools/options and gives good descriptive text)
Would be a really good start, and worth spending time on, on its own.

Once we finish this we can see if we have the capacity to maintain
more documentation.

> -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.

Agree, a problem we have is its not clear who is really going to be involved.
We could postpone defining a **team** until we can see who becomes
active working on the manual.

> I'm not just pointing out what you should do. I'm also offering my help in
> whatever you need.

Thats great, and I see you're been making patches/improvements already.
At the moment its a bit tricky... we still havn't defined if we're
doing a reference manual or not (for eg. though it looks like it
probably will be a referene)

I've talked with Greg Zaal about ways we might focus community efforts
on one area of the manual,
one of us will likely mail the list about this soon.

> 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
>



-- 
- Campbell