<div dir="ltr"><div>In reply to Pep Ribal....</div><div><br></div><div>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.</div><div><br></div><div>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?)</div><div><br></div><div>I will circulate some guidelines for discussion.... </div></div><div class="gmail_extra"><br><div class="gmail_quote">On 14 January 2015 at 07:12, Pep Ribal <span dir="ltr"><<a href="mailto:pepribal@gmail.com" target="_blank">pepribal@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div text="#000000" bgcolor="#FFFFFF">
Hi all, <br>
<br>
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.<br>
<br>
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.<br>
<br>
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).<br>
<br>
Motivation is the key. But how we manage to motivate people to
contribute to the docs?<br>
<br>
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".<br>
<br>
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.<br>
<br>
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.<br>
<br>
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.<br>
<br>
Perhaps other things could be offered, but as a start, these couple
of things would help enough, I think.<br>
<br>
Regards,<br>
<br>
Pep.<br>
<br>
<div>El 14/01/15 a las 08:33, Abuelo S. B.
Chdancer escribió:<br>
</div>
<blockquote type="cite">
<div dir="ltr">
<div>Hi to <span name="Nkansah Rexford">Nkansah Rexford,</span></div>
<div><span name="Nkansah Rexford"><br>
</span></div>
<div><span name="Nkansah Rexford">A contributor should be able
to go to a normal webpage.</span></div>
<div><span name="Nkansah Rexford"><br>
</span></div>
<div><span name="Nkansah Rexford">Register what he would be
interested in doing.</span></div>
<div><span name="Nkansah Rexford"><br>
</span></div>
<div><span name="Nkansah Rexford">Be contacted by a real human
who agrees the task.</span></div>
<div><span name="Nkansah Rexford"><br>
</span></div>
<div><span name="Nkansah Rexford">The writer should be able to
submit using email or a simple web based upload form. For
the text.</span></div>
<div><span name="Nkansah Rexford"><br>
</span></div>
<div><span name="Nkansah Rexford">If approved by an editor or by
peer review the more complicated task of adding
illustrations can be handle by some method.</span></div>
<div><span name="Nkansah Rexford"><br>
</span></div>
<div><span name="Nkansah Rexford"></span><span name="Nkansah
Rexford"><br>
</span></div>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">On 14 January 2015 at 00:47, Nkansah
Rexford <span dir="ltr"><<a href="mailto:nkansahrexford@gmail.com" target="_blank">nkansahrexford@gmail.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid">Hello
Chdancer,
<div><br>
</div>
<div>I think you have a point, and its from a user who's got
no idea what those terms are.</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>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). </div>
<div><br>
</div>
<div>Of course, more flesh can (and likely will) be added to
those getting started pages, but remember not <i>everything
</i>can be covered or all the terminologies can be
expounded.</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>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)</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>rex</div>
<div><br>
On Tuesday, January 13, 2015, Abuelo S. B. Chdancer <<a href="mailto:playadance@gmail.com" target="_blank">playadance@gmail.com</a>>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid">
<div dir="ltr">
<div>Campbell Barton reminded...</div>
<div><br>
</div>
<div>"While this is subjective, we have had
contributions submitted via our<br>
project page:<br>
<br>
<a href="https://developer.blender.org/tag/documentation/" target="_blank">https://developer.blender.org/tag/documentation/</a> "<br>
</div>
<div><br>
</div>
<div> </div>
<div>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.</div>
<div><br>
</div>
<div>I bet a lot of possible contributors give up when
they read this....</div>
<div><br>
</div>
<div>"We have migrated the content over to <tt>reST</tt>
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).</div>
<p>If you want to start contributing or want to have a
look at the new manual, here we have some
instructions.</p>
<h3>How to build the docs locally</h3>
<ul>
<li>Checkout the Subversion repository <tt>svn
checkout <a href="https://svn.blender.org/svnroot/bf-manual/trunk" target="_blank">https://svn.blender.org/svnroot/bf-manual/trunk</a></tt></li>
<li>Move to the location where the repo was cloned</li>
<li>Run <tt>pip install -r requirements.txt</tt>
(Windows user make sure you are using Python 2.7,
not 3.x)</li>
<li>Build a section of the manual (for example <tt>make
render</tt>)</li>
<li>Launch the <tt>contents_quicky.html</tt> inside
of the html folder and browse the freshly build
render docs</li>
</ul>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>What it should say is.....</div>
<div><br>
</div>
<div>Read this (hopefully well written and elegantly
presented) webpage which explains how you register
what you would like to do.</div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>I was in the middle of working on my latest
animation.....</div>
<div><br>
</div>
<div><br>
</div>
<div><br>
</div>
</div>
<span><font color="#888888">
</font></span></blockquote>
</div>
<span><font color="#888888"><br>
<br>
-- <br>
<div dir="ltr"><font color="#666666" size="1"><a href="http://google.com/+Nkansahrexford" target="_blank">+Rexford</a> | <a href="http://africacenter.net" target="_blank">Africa
Center</a> | <a href="https://outreach.wikimedia.org/wiki/Wikipedian_in_Residence" target="_blank">WiR</a> | <a href="http://wikiafrica.net" target="_blank">WikiAfrica</a> | <a href="http://en.wikipedia.org/wiki/User:Nkansahrexford" target="_blank">User:Nkansahrexford</a></font><br>
</div>
<br>
</font></span><br>
_______________________________________________<br>
Bf-docboard mailing list<br>
<a href="mailto:Bf-docboard@blender.org" target="_blank">Bf-docboard@blender.org</a><br>
<a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
<br>
</blockquote>
</div>
<br>
</div>
<br>
<fieldset></fieldset>
<br>
<pre>_______________________________________________
Bf-docboard mailing list
<a href="mailto:Bf-docboard@blender.org" target="_blank">Bf-docboard@blender.org</a>
<a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a>
</pre>
</blockquote>
<br>
</div>
<br>_______________________________________________<br>
Bf-docboard mailing list<br>
<a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
<a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
<br></blockquote></div><br></div>