[Bf-docboard] Documentation status and upgrade proposal

[Campbell Barton]

@Gaia

Yep, I suggest to replace old crap with new crap :), mainly to split
the project into manageable chunks.

I worry if rewriting a manual and switching to a new platform are done
as one step it may take a lot longer (years even).
And if one fails (either the new system or the rewrite), we are left
with something unusable - a half written manual.

If we try to switch to a new technology and fail, then we can blame
the technology... and try something else, or go back to what we have.

If rewriting the manual fails, we can blame our own ability to write
:)... and still end up with better tools/technology and (somewhat
improved docs) - even if we dont manage to get all up to a higher
quality.


Something I want to avoid is to be in an unknown state for a long
time, while we move to a new system we probably want to freeze all
edits to the Wiki manual, but we should try keep that time period as
short as possible IMHO (weeks - some months max).

I realize moving existing docs over may feel like a bad start, but at
least we can do this without long discussions on subjective matters
such as writing style and can even automate the process to some
extent.

If we want to rip out chapters and rewrite after, then theres no
problems with that.


On Fri, May 9, 2014 at 12:47 AM, Gaia <gaia.clary at machinimatrix.org> wrote:
> 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
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard



-- 
- Campbell