[Bf-docboard] Bf-docboard Digest, Vol 111, Issue 9

Tue May 27 15:52:52 CEST 2014

Hi !

It seems to me (by those e-mails) that it's the end of the blenderwiki
project...
Is there a way to make a meeting in IRC about this issue next sunday ?

Cheers !
Ivan Paulos Tomé.

2014-05-27 7:00 GMT-03:00 <bf-docboard-request at blender.org>:

> Send Bf-docboard mailing list submissions to
>         bf-docboard at blender.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         http://lists.blender.org/mailman/listinfo/bf-docboard
> or, via email, send a message with subject or body 'help' to
>         bf-docboard-request at blender.org
>
> You can reach the person managing the list at
>         bf-docboard-owner at blender.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Bf-docboard digest..."
>
>
> Today's Topics:
>
>    1. Re: Documentation status and upgrade proposal (Gaia)
>    2. Re: Documentation status and upgrade proposal (Francesco Siddi)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Mon, 26 May 2014 14:11:28 +0200
> From: Gaia <gaia.clary at machinimatrix.org>
> Subject: Re: [Bf-docboard] Documentation status and upgrade proposal
> To: Blender Documentation Project <bf-docboard at blender.org>
> Message-ID: <53832F70.70901 at machinimatrix.org>
> Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>
> 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
> >
> >
>
>
>
> ------------------------------
>
> Message: 2
> Date: Mon, 26 May 2014 14:39:04 +0200
> From: Francesco Siddi <francesco.siddi at gmail.com>
> Subject: Re: [Bf-docboard] Documentation status and upgrade proposal
> To: Blender Documentation Project <bf-docboard at blender.org>
> Message-ID: <etPan.538335e8.4516dde9.308e at fsiddi-macpro.local>
> Content-Type: text/plain; charset="utf-8"
>
>
> On 26 May 2014 at 14:12:07, Gaia (gaia.clary at machinimatrix.org) wrote:
>
> What is the status of this migration project from wiki to Sphinx ??
> We were investigating some tools to automate part of the initial work?
> https://github.com/ideasman42/blender_manual/commit/d1112412cbec34d4fba07e11408828a37a5ab350
>
>
> What are we waiting for ??
> 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.
>
>
> What is the next step ??
> 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.
>
>
> What does it need to get the next step done ??
> I?ll have another look at the whole thread of mails, summarise and write
> the plan (after consulting with Campbell).
>
>
> 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 ??
> 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.
>
> Francesco
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL:
> http://lists.blender.org/pipermail/bf-docboard/attachments/20140526/2db9430f/attachment.html
>
> ------------------------------
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>
>
> End of Bf-docboard Digest, Vol 111, Issue 9
> *******************************************
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20140527/030d99f7/attachment.htm 