[Bf-docboard] Documentation status and upgrade proposal

[Gaia]

What is the status of this migration project from wiki to Sphinx ?
What are we waiting for ?
What is the next step ?
What does it need to get the next step done ?

Is there a way to transform the wiki documentation into Sphinx
by using scripted converters ? so that we can be sure everything
is in place when we start to improve the documentation ?

cheers,
Gaia

On 08.05.2014 23:24, Campbell Barton wrote:
> @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
>
>