[Bf-docboard] Being involved In documentation

[Campbell Barton]

On Wed, Jan 14, 2015 at 10:32 AM, 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.....


Again, we're aware that the new system has a significantly higher
barrier of entry (as you point out),

This point was raised earlier on in this mailing list and its still a
concern for us.

However the low-barrier-of-entry didn't make the wiki a success either
(we talked about this when proposing the new system).

So, we would still like to make it easier to get involved, longer term
we can look at options for editing files and submitting them
completely online, or have a bundle with everything setup and ready to
go.

But I think its far too Its too early to judge if this is really
prohibitively hard for writers - we're in the process of setting up a
new system,
 so you can for sure find things that obviously need to be improved
still (or are in a poor state).

We can try address pain-points as they show up, but for now we still
have a lot of basics to get right & we can't solve everything at once.


-- 
- Campbell