[Bf-docboard] Being involved In documentation
Pep Ribal
pepribal at gmail.com
Wed Jan 14 07:12:28 CET 2015
Hi all,
I understand the disappointment that the new documentation system has
caused. I also think that it builds a big barrier for the people who
want to help with documentation writing. It's true that the wiki made it
much more simple to help, but I agree with Campbell that even the
simplicity of the wiki didn't motivate people enough. And that means
that technology was not the problem. I think the technology (wiki) was
the right one to use, but the project lacked (and still lacks) something
more.
The key question is: why isn't people motivated? For instance, Blender
development has a huge entry barrier, compared to wiki, and even
compared to the new reST-SVN system. However, activity is way bigger in
development than in documentation. One does not expect that a project as
big as Blender is suffering from a extremely low documentation
development pace.
I've been working with Blender since many years ago, but I was away from
it for a while. Now that I'm back, I see the same eternal problem that
was present before: documentation is the worst of Blender, by far. And I
don't see it changing any time soon, unless something is done. And I
don't think a change in technology is the response (and even less a
change that raises the entry barrier).
Motivation is the key. But how we manage to motivate people to
contribute to the docs?
I think that some Project Management skills should be poured in. A
"project manager" should be appointed. A few key positions should be
filled (official writers), and an official documentation team should be
set up. If we have a team of developers, an official team, with a clear
coordinator and a clear team of key developers, each one responsible for
his module, why not have the same for documenters? That's what the
documentation project lacks. There is no official team. So there is not
a feeling of "important department".
Why do we need an official team? Because there's no more motivating
thing than feeling officially part of something. In this case, the
«official Blender documentation team». And not only feeling that, but
also seeing it, for instance, in the appropriate page in Blender
website: names and functions of every «official» member of that team. I
think that would attract writers.
But it shouldn't only be a list of names in a web page. Being part of
the team should offer additional «privileges». The more of them we can
give, the more motivation writers will have.
What should be offered to writers besides credit? I think one of the
most important things is attention from the developer responsible for
the documented module. This is a crucial part in all this.
Perhaps other things could be offered, but as a start, these couple of
things would help enough, I think.
Regards,
Pep.
El 14/01/15 a las 08:33, Abuelo S. B. Chdancer escribió:
> Hi to Nkansah Rexford,
>
> A contributor should be able to go to a normal webpage.
>
> Register what he would be interested in doing.
>
> Be contacted by a real human who agrees the task.
>
> The writer should be able to submit using email or a simple web based
> upload form. For the text.
>
> If approved by an editor or by peer review the more complicated task
> of adding illustrations can be handle by some method.
>
>
>
> On 14 January 2015 at 00:47, Nkansah Rexford <nkansahrexford at gmail.com
> <mailto:nkansahrexford at gmail.com>> wrote:
>
> Hello Chdancer,
>
> I think you have a point, and its from a user who's got no idea
> what those terms are.
>
> However, look at it this way too. Trying to explain every single
> detail of the steps will require another documentation on its own.
> "What repo is?", "How to clone", "What is reST?", svn (what is
> even version control? duh!), checkout (what am I buying?), pip,
> requirements.txt and so on.
>
> Those are stuffs with detailed documentations on their own found
> everywhere on the net. I don't think the getting started page on
> Blender should aggregate all these information and present it to
> anyone who actually wants to get started (beside's that'll be
> aggregating documentations into a documentation).
>
> Of course, more flesh can (and likely will) be added to those
> getting started pages, but remember not /everything /can be
> covered or all the terminologies can be expounded.
>
> I think explaining every single thing on that page defeats the
> whole idea of 'getting started'. Its not a training course. Its to
> get you started, so they're pointers, offering guidance as to how
> to go about it.
>
> Therefore, I think as someone who really wants to get started,
> doing a bit more googling and reading outside the getting started
> page should make things happen much easier, for both authors of
> get started pages and also the 'get-startee' (bad english, but
> hope you get it)
>
> I know its hard to understand pages like that, but I hope it gets
> improved to the best possible to bridge the gap between devs and
> users.
>
> rex
>
> On Tuesday, January 13, 2015, Abuelo S. B. Chdancer
> <playadance at gmail.com <mailto:playadance at gmail.com>> wrote:
>
> Campbell Barton reminded...
>
> "While this is subjective, we have had contributions submitted
> via our
> project page:
>
> https://developer.blender.org/tag/documentation/ "
>
> Guys, someone who USES Blender may not know the first thing
> about coding, someone who can write simple prose explaining to
> another person in clear language how to DO something artistic
> may be totally useless when it comes to installing software or
> plugging in a USB plug.
>
> I bet a lot of possible contributors give up when they read
> this....
>
> "We have migrated the content over to reST format, so that the
> manual can be built with Sphinx. A good amount of work is
> still required to complete the migration (learn more about the
> open tasks in Phabricator).
>
> If you want to start contributing or want to have a look at
> the new manual, here we have some instructions.
>
>
> How to build the docs locally
>
> * Checkout the Subversion repository svn checkout
> https://svn.blender.org/svnroot/bf-manual/trunk
> * Move to the location where the repo was cloned
> * Run pip install -r requirements.txt (Windows user make
> sure you are using Python 2.7, not 3.x)
> * Build a section of the manual (for example make render)
> * Launch the contents_quicky.html inside of the html folder
> and browse the freshly build render docs
>
>
> That is a hundred times worse than trying to use the wiki
> manual. It is mindboggingly offputting and not just
> incomprehensible but presents such a hurdle that most people
> will stop at that point and forget being involved.
>
> What it should say is.....
>
> Read this (hopefully well written and elegantly presented)
> webpage which explains how you register what you would like to do.
>
> If worried about 'no nothings' writing drivel, that is why we
> invented human editors. Also it is technically possible to
> have peer reviews of submitted entries prior to making the
> entry official.
>
> I was in the middle of working on my latest animation.....
>
>
>
>
>
> --
> +Rexford <http://google.com/+Nkansahrexford> | Africa Center
> <http://africacenter.net> | WiR
> <https://outreach.wikimedia.org/wiki/Wikipedian_in_Residence> |
> WikiAfrica <http://wikiafrica.net> | User:Nkansahrexford
> <http://en.wikipedia.org/wiki/User:Nkansahrexford>
>
>
> _______________________________________________
> 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/20150114/1a2b0efd/attachment.htm
More information about the Bf-docboard
mailing list