[Bf-docboard] Documentation status and upgrade proposal

[Campbell Barton]

On Thu, May 8, 2014 at 11:48 AM, koil . <dd4567 at hotmail.co.uk> wrote:
> The proposal I guess is to:
> 1: Change the webpage and format to rst.
> 2: Also to transform the content into a different style, I presume.
>
> I agree with 1. So Ill try talk about 2.
>
> To give a good opinion on 2. first I would have to review the pages on the
> proposed webpage, learn the content.
> Then I would have to try imagine or try transform other parts of the blender
> manual.
> Only then I can give a valid opinion.
>
> If the developers want to change the type of content added to the manual, I
> would like to see how this goes.
> Im still yet to learn how the new content is ordered and written.
>
> I like the idear of Bug Report/Todo, I think this is better than old reviews
> that are hard to maintain on media wiki, and dont often get updated.
> If users can say something is wrong with the wiki, its easier then for
> someone to add a todo, then its easier for someone to propose a fix.
>
> If there are less types of content, like UI Reference, Menu Reference,
> Editing Reference.
> I think that will be better, less to write which is already known, and less
> to translate.
> And also people can spend more time writing better content for Intros and
> Elements.
>
> I havnt seen much Editing or Workflow yet in the new content, but Cycles
> Rendering is more about Elements than Editing or Workflow.
> Though I havnt really read much of it yet.
>
> For example, how would new content style apply to Animation or Rigging.
> If its just Elements, I guess it would be well presented examples, of what
> each part of the system is used for.
> Shape Keys, Pose Lib, Inverse Kinematics, etcetera.
>
> The wiki manual is good fun, but I feel likes its a dead system sometimes.
> Maybe it will be good reference for what to add to the new manual.
>
> If the above is true about the content, its a bit depressing but, probably
> for the best.
> There any many tutorials online, so a complete intro to blender manual will
> probably be better than broken mix of things.
>
> Koilz.


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`.

If some docs are very low quality or out of date, they could be left out.

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

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.