[Bf-docboard] Proposal for restructuring the user manual

[Campbell Barton]

On Sun, Dec 28, 2014 at 7:21 PM, Greg Zaal <gregzzmail at gmail.com> wrote:
> Hey guys,
>
> Overall, I like the proposal and agree with most of the comments so far,
> with a few little notes:
>
> About videos: I agree that they're generally a problem to maintain and
> internationalize, though a video with no voice which simply shows the
> results of something (e.g. ocean modifier includes:
> http://vimeo.com/18911131 ) is perfectly fine imo.
>
> A section on editors is a good idea, as long as we're not duplicating
> anything too much. I see it as a place to describe the editors themselves,
> and link to the other relevant sections when mentioning a feature.
>
> Now about restructuring the whole manual:
>
> When will "good timing" come? I'd prefer if we get all big restructuring
> done fairly soon (before February perhaps). It doesn't have to be a
> gargantuan task undertaken by only a handful of people - it may be easier to
> start from the ground up and get module owners and volunteers to work on a
> section each.
>
> These people would become the "section owners" mentioned in
> http://blender.org/documentation/contribute. We could rename the /manual
> folder to /manual_old, and then they could scrub through the old manual for
> their relevant content and move them to a new /manual folder. This way,
> it'll be easy to tell what's still left to move (stuff still in
> /manual_old), and keep note of where things were moved to so that it'll be
> easier to fix all the broken links caused by the move.
>
> Cheers,
> Greg


Moving pages over to a new structure manually seems makes me worry
that the manual will be left in a brolen state for too long (we could
do in a branch... but its only hiding the issue, not solving it).

I think its a few hours work (max) for me to make an RST remapping
tool, where you can snapshot the state of the manual, all the files
(rename files/directories etc), then apply the snapshot to update all
the interlinking references. The index pages would likely need to be
redone still, but thats no big deal.

Suggest:

- agree on new structure.
- use an RST remapping tool to apply the structure.
- manually do any other changes, improving index, introduction,
anything requiring to move text between pages (merge/split/delete
pages... etc).

The first 2 steps we should be able to do rather quickly, the third
can be ongoing polish/organization and apart of regular manual
improvements.