[Bf-docboard] Specific plans and discussion of what our manual should be and how to get it

[Greg Zaal]

Hey Abuelo,

We discussed what the new manual should be a little while ago on this list
- there seemed to be a general consensus that it should be both a technical
reference ("button X does this") and a topic-driven guide. Different
sections of the manual are suited to either one or both of those. (See the
archives
<http://lists.blender.org/pipermail/bf-docboard/2015-January/thread.html>,
in thread "Proposal for restructuring the user manual").

Breaking it up into sub-editors, authors and contributors is an interesting
idea. I agree that someone should be able to suggest a change to the manual
without needing to set up SVN, but this can already be done by creating a
task here: https://developer.blender.org/maniphest/task/create/?project=53.
Being a sub-editor would be a pretty crappy "job" I think - receive emails
from random people demanding you to make some change, and then you're left
to sort out correct formatting, uploading images and commit it.

Sending an email to every blender user 2 weeks after they download it is
not acceptable at all IMO, but you can easily start a thread on
blenderartists.org to ask them (possibly do a poll there).

I think it would be best if you could join our IRC channel for a few
minutes (click here
<http://webchat.freenode.net?nick=abuelo...&channels=%23blenderwiki&uio=d4>,
type in the captcha, and you're in) to chat with us - just to make sure
we're all on the same page and to avoid starting discussions that have
already been had.

Finally, I'd really appreciate if you try to set up SVN and make some edits
to the manual (here's a simple guide I wrote to help:
http://blender.org/manual/about/install/windows.html) - it's really not as
hard or complicated as you think it is - I'm primarily an artist myself.

Cheers,
Greg Zaal

On 14 January 2015 at 16:12, Abuelo S. B. Chdancer <playadance at gmail.com>
wrote:

> Top level design:
>
> What should a manual be and how do we get one?
>
> 1) Quick reference guide to all commands?
>
> 2) Topic based manual of what you might want to do and how to do it?
>
> 3) A place to learn step by step?
>
> Lower level design:
>
> What is a normal page to look like?
>
> How should one page lead or connect to another? (Has the tech already set
> this?)
>
> What should the overall plan for the entire work be?
>
> Contributors:
>
> Finding that rare combination of someone who intimately knows parts of
> Blender and is willing and able to explain it to someone who doesn't
> understand shouldn't be messed up by also requiring that person to be
> technically proficient and willing to learn new software simply to tell
> their story.
>
> If that software is needed to get the text and pictures into the server -
> let those who use it be *sub-editors* and let the *authors* communicate
> with sub-editors using simple software that everyone already has - email &
> browser.
>
> I would tell other potential contributors that they need to indicate in a
> simple webform what they feel able to help on, and tell them that sending
> in their contribution will be technically similar to posting a comment on a
> website - nothing to download, no programming skills needed.
>
> The various ideas would need to be cut down to practical designs and could
> then be again displayed on webpages for public review.
>
> When the design of the work has been decided which includes details of
> what individual pages should have in common and what should be different
> the minor stylistic decisions can be made about whether writing is to say
> "You can" rather than "It is possible to.."
>
>  We need a few web pages that everyone who downloads blender would be
> asked to review asking them to rate which concepts they think would be
> useful for them in learning or using Blender.
>
> I would do a survey of users to try to understand what they/we need or
> want from documentation.
>
> I would send an email to anyone who downs Blender, about 2 weeks later
> asking them to comment on what causes them problems, on where they look for
> information, on how they are learning. I would read them all to get a feel
> for the problem.
>
>  So I suggest the following:
>
> Those who already have downloaded whatever that stuff is that I couldn't
> even be bothered to read - they should be initially *sub-editors *who can
> receive contributions from other simpler folks like me, that *sub-editor*
> then uses that software stuff to get the data onto the server.
>
> Some web page creating type is needed to set-up the following fairly
> simple webpages that I am suggesting, or something similar where normal
> contributors can register their willingness and their self-claimed level of
> expertise. I would be happy to work with the webpage creator.
>
> I would be happy to help plan a few web pages that everyone who downloads
> blender would be asked to review asking them to rate which concepts they
> think would be useful for them in learning or using Blender.
>
> The server should send an email anyone who downs Blender, about 2 weeks
> later asking them to comment on what causes them problems, on where they
> look for information, on how they are learning. We should all read them all
> to get a feel for the problem.
>
>  It may be that others on this list that is out there somewhere have much
> better ideas than mine, but if we don't come up with a better plan this is
> the default that I suggest:
>
> I and a web page creator put on Blender.org the following new webpages
> directly linked as the documentation page.
>
> "Register in this form if you would like to be involved in creating a
> great manual for a great program."
>
> The form would contain questions for the contributor to define in what way
> they can help.
>
> They can choose to be
>
> *sub-editors* who download software and get their fingers into the
> servers data or
>
> *authors * who write explaining command or who write explaining methods
> or
>
> *contributors* who want to voice what they would like to see in the
> manual but who are not capable of actually doing it (newbies have the right
> to say what they need, but obviously they can't provide it)
>
> Decisions or plans of what the manual should contain and BE, would be
> published on those pages with feedback forms to check if it's what users
> probably want.
>
> Please make your suggestions.
>
> Do you want to build those webpages?
>
>
> _______________________________________________
> 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/20150114/987cce19/attachment.htm