[Bf-committers] Documentation editing is not user friendly

[Campbell Barton]

On Thu, Jan 28, 2016 at 7:48 AM, Knapp <magick.crow at gmail.com> wrote:
> I have been working on making a video about the VSE. I thought it would be
> easy but it turns out not to be because of a lot of factors including my
> computer.
>
> To get to the point, the VSE documentation is quite bad. I know it is being
> worked on by someone and I thought I would help him since I was rereading
> everything anyway. But it turned out to be very hard to do.
>
> I thought it would be like Wikipedia, you edit it and it is done. That is
> NOT the way it is. You must first be signed up. You must download a copy of
> the source document code and then you must change that in a funny editors
> language and then you must compile it on your computer. Then you have to
> submit it as if were were writing C code.
>
> Guess what? I could not get it to compile on Sabayon Linux. I don't have
> time to fight with it but I did ask and got a nice reply that he would just
> take my ideas and do it for me. All (not the nice guy) this results in me
> being VERY put off from helping with the documentation. I am sure I am not
> the first to run into this big wall.

When moving to sphinx we knew the up-front effort involved would be greater,
however I think you over state the complexity.

You don't need an account to build the docs locally, having an account
to commit is no different from needing a wiki account.
The reStructuredText markup is similar complexity to MediaWiki or
Phabricators remarkup.

On a typical Linux system its around 5 commands install dependencies,
download the manual and build it.
If any of these fail its frustrating, but let us know what when wrong,
likely its not hard to overcome.

> I am good with computers but this was WAY too much for me to go through.
> Think what it must be like for the computer phobic artists? It is just
> simply to hard for the average person to bother with. It is no wonder that
> the documentation is so bad. We need to do something to make this light an
> easy.

Agree documentation quality is very mixed - some sections are still
copied from the Wiki.

One of the main reasons to move *away* from the Wiki was the overall
low quality and lack of quality control we had there
(many half finished pages copy-pasted information between pages, drive
by edits with incomplete, even misinformation).

After ~5 years of having Blender 2.5+ out many wiki pages weren't
updated from Blender 2.4x for example.

This is re-opening discussion we had a while back:
http://lists.blender.org/pipermail/bf-docboard/2014-May/004453.html

New manual system is of course not above criticism,
but its really a stretch to blame it for the state of documentation
having migrated documentation written over ~10year time period,
when the new systems been in use for over a year.

> Ton said that we need someone to interface between the users and the
> developers to let them know about new stuff and how it all works. This is
> the job of the manual and if the manual were as great and cool as the 2.4
> manual then I think we would not need someone to do this so badly for us.
> We need to improve the "new" manual a LOT. It needs to be easy to do.
>
> I think it would be a great idea to move to a system like Wikipedia.
>
> Sorry if this is not the right place to post this but I did not find
> another place.
>
> Let's make working on the manual as easy as helping with Wikipedia!
>
> Thanks,
>
> --
> Douglas E Knapp
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers



-- 
- Campbell