<div dir="ltr"><div><div><div>Hi !<br><br></div>It seems to me (by those e-mails) that it's the end of the blenderwiki project...<br></div>Is there a way to make a meeting in IRC about this issue next sunday ?<br></div>
<div><div><div><br></div><div>Cheers !<br></div><div>Ivan Paulos Tomé.<br></div></div></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">2014-05-27 7:00 GMT-03:00 <span dir="ltr"><<a href="mailto:bf-docboard-request@blender.org" target="_blank">bf-docboard-request@blender.org</a>></span>:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Send Bf-docboard mailing list submissions to<br>
<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a><br>
<br>
To subscribe or unsubscribe via the World Wide Web, visit<br>
<a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
or, via email, send a message with subject or body 'help' to<br>
<a href="mailto:bf-docboard-request@blender.org">bf-docboard-request@blender.org</a><br>
<br>
You can reach the person managing the list at<br>
<a href="mailto:bf-docboard-owner@blender.org">bf-docboard-owner@blender.org</a><br>
<br>
When replying, please edit your Subject line so it is more specific<br>
than "Re: Contents of Bf-docboard digest..."<br>
<br>
<br>
Today's Topics:<br>
<br>
1. Re: Documentation status and upgrade proposal (Gaia)<br>
2. Re: Documentation status and upgrade proposal (Francesco Siddi)<br>
<br>
<br>
----------------------------------------------------------------------<br>
<br>
Message: 1<br>
Date: Mon, 26 May 2014 14:11:28 +0200<br>
From: Gaia <<a href="mailto:gaia.clary@machinimatrix.org">gaia.clary@machinimatrix.org</a>><br>
Subject: Re: [Bf-docboard] Documentation status and upgrade proposal<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID: <<a href="mailto:53832F70.70901@machinimatrix.org">53832F70.70901@machinimatrix.org</a>><br>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed<br>
<br>
What is the status of this migration project from wiki to Sphinx ?<br>
What are we waiting for ?<br>
What is the next step ?<br>
What does it need to get the next step done ?<br>
<br>
Is there a way to transform the wiki documentation into Sphinx<br>
by using scripted converters ? so that we can be sure everything<br>
is in place when we start to improve the documentation ?<br>
<br>
cheers,<br>
Gaia<br>
<br>
On 08.05.2014 23:24, Campbell Barton wrote:<br>
> @Gaia<br>
><br>
> Yep, I suggest to replace old crap with new crap :), mainly to split<br>
> the project into manageable chunks.<br>
><br>
> I worry if rewriting a manual and switching to a new platform are done<br>
> as one step it may take a lot longer (years even).<br>
> And if one fails (either the new system or the rewrite), we are left<br>
> with something unusable - a half written manual.<br>
><br>
> If we try to switch to a new technology and fail, then we can blame<br>
> the technology... and try something else, or go back to what we have.<br>
><br>
> If rewriting the manual fails, we can blame our own ability to write<br>
> :)... and still end up with better tools/technology and (somewhat<br>
> improved docs) - even if we dont manage to get all up to a higher<br>
> quality.<br>
><br>
><br>
> Something I want to avoid is to be in an unknown state for a long<br>
> time, while we move to a new system we probably want to freeze all<br>
> edits to the Wiki manual, but we should try keep that time period as<br>
> short as possible IMHO (weeks - some months max).<br>
><br>
> I realize moving existing docs over may feel like a bad start, but at<br>
> least we can do this without long discussions on subjective matters<br>
> such as writing style and can even automate the process to some<br>
> extent.<br>
><br>
> If we want to rip out chapters and rewrite after, then theres no<br>
> problems with that.<br>
><br>
><br>
> On Fri, May 9, 2014 at 12:47 AM, Gaia <<a href="mailto:gaia.clary@machinimatrix.org">gaia.clary@machinimatrix.org</a>> wrote:<br>
>> Hi;<br>
>><br>
>> As much as i would like to get this migration done quickly,<br>
>> i still have doubts about what you propose as the migration path.<br>
>> I just write down what i think and believe and i just try to be<br>
>> straight :)<br>
>><br>
>> On 08.05.2014 05:46, Campbell Barton wrote:<br>
>>> Suggest not attempt to improve docs at the same time as migrating to<br>
>>> new system, runs risk of migration never getting done.<br>
>>><br>
>>> First just migrate all wiki docs to new manual `as-is`.<br>
>> Well, the current wiki is a mixture of documents that have been migrated<br>
>> from Blender 2.4 and newer work. And it looks to me like the old documents<br>
>> tend to be mostly kept as they are because nobody ever wanted(dared?) to<br>
>> touch them.<br>
>><br>
>> Why would that change when the wiki is migrated one to one to a newer<br>
>> platform ? How would documentors become motiviated to finally change<br>
>> documents which have already been kept untouched for years ?<br>
>><br>
>> I am afraid that when the transition to another documentation platform<br>
>> is made by "first copy what we have, then think about restructuring" will<br>
>> in the best case end with a better structure lots of reorganising work<br>
>> and tons of outdated documents.<br>
>><br>
>> And then document creators still have to decide for each document whether<br>
>> it needs to be rewritten, removed, or just updated to newer information.<br>
>><br>
>> From user point of view, it looks more like "replace old crap with new<br>
>> crap" ;-/<br>
>> and you can never be sure if what you see in the docs is up to date.<br>
>>> If some docs are very low quality or out of date, they could be left out.<br>
>> What are the criterions for classifying a document as low quality ?<br>
>><br>
>>> After that. organize how to improve docs themselves, perhaps focus on<br>
>>> 1-2 chapters just to prove the new system works well.<br>
>> Why not just work in the opposite way? Why not first think about a good<br>
>> structure, define what shall be put into the docs and what should be<br>
>> left out ?<br>
>> Then start the new documentation (something easy for the beginning) ,<br>
>> improve<br>
>> the general document structuring while working on one initial chapter,<br>
>> use the "old wiki" where appropriate, but copy information only after<br>
>> careful<br>
>> inspection (word by word...)<br>
>><br>
>> This approach would start with a blank documentation. While working on<br>
>> the docs the overall structure might change over time. But it would be a<br>
>> very<br>
>> honest approach at least:<br>
>><br>
>> 1.) The users can SEE how the documentation grows,<br>
>> 2.) The document creators can ensure that whatever gets into the new<br>
>> documentation is mostly up to date at the time when it was created.<br>
>><br>
>>> At that point we probably know if this is something to stick with (and<br>
>>> remove wiki manual), or if for some reason its a lot worse and can't<br>
>>> be improved, we scrap the migration altogether.<br>
>> I also believe that putting work into "define the document structure"<br>
>> can be made<br>
>> independent from what platform is actually used. Actually i even could see<br>
>> that we first define a robust and user friendly structure in the wiki, then<br>
>> start to reorganize the documentation in the wiki (to prove the<br>
>> restructuring)<br>
>> and finally think about migration to a platform that supports<br>
>><br>
>> - versioning and<br>
>> - internationalisation<br>
>><br>
>> The proposed platform looks good to me, i also can live without having<br>
>> a web frontend and a Wysiwyg editor. But i suspect that first selecting<br>
>> the technology then thinking about how it can be used is the wrong<br>
>> approach :)<br>
>><br>
>> And i would rather see a small document collection that is correct<br>
>> than a large collection where the user never knows if a document<br>
>> in it is reliable or not.<br>
>><br>
>> cheers,<br>
>> Gaia<br>
>> _______________________________________________<br>
>> Bf-docboard mailing list<br>
>> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
>> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
><br>
><br>
<br>
<br>
<br>
------------------------------<br>
<br>
Message: 2<br>
Date: Mon, 26 May 2014 14:39:04 +0200<br>
From: Francesco Siddi <<a href="mailto:francesco.siddi@gmail.com">francesco.siddi@gmail.com</a>><br>
Subject: Re: [Bf-docboard] Documentation status and upgrade proposal<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID: <etPan.538335e8.4516dde9.308e@fsiddi-macpro.local><br>
Content-Type: text/plain; charset="utf-8"<br>
<br>
<br>
On 26 May 2014 at 14:12:07, Gaia (<a href="mailto:gaia.clary@machinimatrix.org">gaia.clary@machinimatrix.org</a>) wrote:<br>
<br>
What is the status of this migration project from wiki to Sphinx ??<br>
We were investigating some tools to automate part of the initial work?<a href="https://github.com/ideasman42/blender_manual/commit/d1112412cbec34d4fba07e11408828a37a5ab350" target="_blank">https://github.com/ideasman42/blender_manual/commit/d1112412cbec34d4fba07e11408828a37a5ab350</a><br>
<br>
<br>
What are we waiting for ??<br>
We are waiting to do a couple more tests and make a public plan so that volunteers can contribute in checking the generated RST docs. At the moment the translations and illustrations issues are being evaluated.<br>
<br>
<br>
What is the next step ??<br>
The next step would be announcing a migration plan on this list. I?ve been meaning to do this for a bit, will do asap.<br>
<br>
<br>
What does it need to get the next step done ??<br>
I?ll have another look at the whole thread of mails, summarise and write the plan (after consulting with Campbell).<br>
<br>
<br>
Is there a way to transform the wiki documentation into Sphinx?<br>
by using scripted converters ? so that we can be sure everything?<br>
is in place when we start to improve the documentation ??<br>
Yes there is a way (see first link). It will not be magic, so some people need to be around during that time of transition.<br>
<br>
Francesco<br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <a href="http://lists.blender.org/pipermail/bf-docboard/attachments/20140526/2db9430f/attachment.html" target="_blank">http://lists.blender.org/pipermail/bf-docboard/attachments/20140526/2db9430f/attachment.html</a><br>
<br>
------------------------------<br>
<br>
_______________________________________________<br>
Bf-docboard mailing list<br>
<a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
<a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
<br>
<br>
End of Bf-docboard Digest, Vol 111, Issue 9<br>
*******************************************<br>
</blockquote></div><br></div>