[Bf-docboard] Documentation status and upgrade proposal

[Campbell Barton]

Hi, I wasn't aware of this list existing, but I was involved with the
proposal to move the manual to a new system, will give some replies.



@brita

> Besides Manual, Dev and Tutorial also fit well in this scheme.

Not sure about this. Probably we can leave tutorials to other web
sites (there are many), and Dev docs Im happy to keep on wiki for now.
Since they fit the scheme of random-linked-pages, much better. (as in
- they dont need to read so much like a book).

On the other hand, if this system works well, Im not totally against
moving other parts of our wiki to it, But suggest to hold off until
the manual has proven to be a success.



@Jeffrey H

Not sure what you mean about "linking" RestructuredText has a fairly
nice method to add in cross-references and you can link to external
sites too, I don't see this as an issue.

but agree "user contributions" is a concern. There is the idea that
making user contributions `easy` is the best way to get a document
done,

But IMHO the flip side of this --- is you get a lot of half edited
pages, people start pages and dont finish them, and we get edits that
probably should be reviewed or even rejected because of poor quality.
Not to say editing documentation should be made difficult, just that
the current wiki system has _not_ given us a really great manual IMHO
(though parts of it are great of course).

Currently we have a situation where docs are *broken* and thats
considered normal, I think with a better system authors can be in a
bit more control and not just have random 2.4x pages mixed in with
2.5x, 2.6x, 2.7x docs.
However at the end of this day this is still work someone has to do,
our-millage-may-vary :)

Eventually I would like that the manual is a complete-document,
covering areas of Blender in a clear & concise way, if something is
incorrect or missing, this is reported as a bug/issue,
it gets fixed before release, and we have some valuable resources we
can include with Blender - basically manage this closer to how we
manage Blender source code and releases.

Your last point about using a wiki to supplement is well taken, but I
dont think its unique to wiki's --- the manual can link to any
external resource when it makes sense to.



@marco ardito

re - contributions, right, users can prepare docs on a wiki, on
github, anywhere... then submit for inclusion.
Since this is just a directory of files we're not locked into one way
of doing things.
For the Python API docs, sometimes I've just got mails containing
improvements, but Id like if we had something a bit nicer.

Expecting documentation authors to use git may be unrealistic, however
github does have a way to edit text online and commit (without having
to install git locally).

Note that we aren't locked into git, if we find some other system
better for authors, we can move to that too.


Your point about a manual not just being a reference is important,
some wiki pages in our current manual - list every button in a panel
with their tooltips,
In most cases i dont think this really helps, its not giving insights
into how things work or showing users why they might use certain
features.

But I think this is orthogonal to which system is used, and am a bit
worried if we try to migrate the manual to a new system at the same
time as rewriting a lot, that it never gets finished.


As for translations, while there is no special support for it (which
could be nice to have), It could work out fine just to use branches,
translators can review commits made since they last translated and
update their versions if needed.

-- 
- Campbell