[Bf-docboard] Being involved In documentation

Wed Jan 14 14:19:20 CET 2015

On Wed, Jan 14, 2015 at 11:54 PM, Abuelo S. B. Chdancer
<playadance at gmail.com> wrote:
> In reply to Pep Ribal....
>
> Absolutely. The surprise is that some of what you suggest has been done, but
> who would know? There are people who are listed as being in charge of bits
> of the manual, the list is somewhere on some server, I have forgotten where.
>
> It is an odd fact that more people want to code than explain the code. This
> has been the case in the computer industry for decades and the lousy level
> of most manuals is the result. My new hard disk drive comes with a manual
> that warns not to connect the drive when the computer is on. How do you read
> this manual? - It's in pdf format on the drive.  (Anyone notice a problem
> with this?)
>
> I will circulate some guidelines for discussion....
>
> On 14 January 2015 at 07:12, Pep Ribal <pepribal at gmail.com> wrote:
>>
>> 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>
>> 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> 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 | Africa Center | WiR | WikiAfrica | User:Nkansahrexford
>>>
>>>
>>> _______________________________________________
>>> 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