[Bf-docboard] Manual scope
Gaia
gaia.clary at machinimatrix.org
Sun Jan 25 13:00:22 CET 2015
#################
3 Questions...
#################
come into my mind every timewhen 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 Blenderas 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 browsedwith 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
> <mailto: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 <mailto: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 <mailto: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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20150125/cf1146a2/attachment.htm
More information about the Bf-docboard
mailing list