[Bf-docboard] Documentation status and upgrade proposal

[Gaia]

Hi;

As much as i would like to get this migration done quickly,
i still have doubts about what you propose as the migration path.
I just write down what i think and believe and i just try to be
straight :)

On 08.05.2014 05:46, Campbell Barton wrote:
> Suggest not attempt to improve docs at the same time as migrating to
> new system, runs risk of migration never getting done.
>
> First just migrate all wiki docs to new manual `as-is`.
Well, the current wiki is a mixture of documents that have been migrated
from Blender 2.4 and newer work. And it looks to me like the old documents
tend to be mostly kept as they are because nobody ever wanted(dared?) to
touch them.

Why would that change when the wiki is migrated one to one to a newer
platform ? How would documentors become motiviated to finally change
documents which have already been kept untouched for years ?

I am afraid that when the transition to another documentation platform
is made by "first copy what we have, then think about restructuring" will
in the best case end with a better structure lots of reorganising work
and tons of outdated documents.

And then document creators still have to decide for each document whether
it needs to be rewritten, removed, or just updated to newer information.

 From user point of view, it looks more like "replace old crap with new 
crap" ;-/
and you can never be sure if what you see in the docs is up to date.
> If some docs are very low quality or out of date, they could be left out.

What are the criterions for classifying a document as low quality ?

> After that. organize how to improve docs themselves, perhaps focus on
> 1-2 chapters just to prove the new system works well.

Why not just work in the opposite way? Why not first think about a good
structure, define what shall be put into the docs and what should be 
left out ?
Then start the new documentation (something easy for the beginning) , 
improve
the general document structuring while working on one initial chapter,
use the "old wiki" where appropriate, but copy information only after 
careful
inspection (word by word...)

This approach would start with a blank documentation. While working on
the docs the overall structure might change over time. But it would be a 
very
honest approach at least:

1.) The users can SEE how the documentation grows,
2.) The document creators can ensure that whatever gets into the new
documentation is mostly up to date at the time when it was created.

> At that point we probably know if this is something to stick with (and
> remove wiki manual), or if for some reason its a lot worse and can't
> be improved, we scrap the migration altogether.

I also believe that putting work into "define the document structure" 
can be made
independent from what platform is actually used. Actually i even could see
that we first define a robust and user friendly structure in the wiki, then
start to reorganize the documentation in the wiki (to prove the 
restructuring)
and finally think about migration to a platform that supports

- versioning and
- internationalisation

The proposed platform looks good to me, i also can live without having
a web frontend and a Wysiwyg editor. But i suspect that first selecting
the technology then thinking about how it can be used is the wrong
approach :)

And i would rather see a small document collection that is correct
than a large collection where the user never knows if a document
in it is reliable or not.

cheers,
Gaia