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

Ivan Paulos Tomé greylica at gmail.com
Wed May 28 14:48:13 CEST 2014 

OK,

After the last conversations in IRC, I was able to understand.
The blenderwiki project will continue here for us.

I have another question:
Since rna_wiki_reference.py is the direct link to the wiki manual,
and the plan is to link Blender with the html docs, what can
we do about translated manuals ?

I mean, I have been using the file rna_wiki_reference.py to
link Blender translated to pt_BR and pt
to this manual: (And I was working to link them with the EN wiki too) :

http://wiki.blenderfarmbrasil.com.br/index.php/Doc:PT/2.6/Manual

So, the question is if will we still be able to use this file to link
localized interfaces with their proper translated manual pages.

If the plan is to add another option in the right click context,
in which we can link to localized manpages as well as to localized wikis,
I will consider this move a very good move, because we will be able to
consult
the best of both worlds. We can see the manual that Blender Foundation
will provide us, and at the same time, translate/localize those pages
in the wiki contexts using rna_wiki_reference.py.

Cheers !


2014-05-28 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: Bf-docboard Digest, Vol 111, Issue 9 (Ivan Paulos Tom?)
>    2. Re: Bf-docboard Digest, Vol 111, Issue 9 (Campbell Barton)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Tue, 27 May 2014 10:52:52 -0300
> From: Ivan Paulos Tom? <greylica at gmail.com>
> Subject: Re: [Bf-docboard] Bf-docboard Digest, Vol 111, Issue 9
> To: bf-docboard at blender.org
> Message-ID:
>         <
> CA+Zt8s7o8WdzauRtLUN3_CE-5S+YT8vb0pERfdpAd5jsTtdzkQ at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> 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.html
>
> ------------------------------
>
> Message: 2
> Date: Wed, 28 May 2014 02:43:54 +1000
> From: Campbell Barton <ideasman42 at gmail.com>
> Subject: Re: [Bf-docboard] Bf-docboard Digest, Vol 111, Issue 9
> To: Blender Documentation Project <bf-docboard at blender.org>
> Message-ID:
>         <
> CAEcf3NxuHBPq6790igQuOQoVyyvorBDpmKYgSxZGbWjaQtcOhg at mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8
>
> On Tue, May 27, 2014 at 11:52 PM, Ivan Paulos Tom? <greylica at gmail.com>
> wrote:
> > 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?.
>
> This isn't the plan,
>
> If you check the main wiki page:
>
> http://wiki.blender.org
>
> The only difference will be "User Manual" will link to generated html docs,
> just like the "Python API Reference" does currently.
>
>
> ------------------------------
>
> _______________________________________________
> 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 10
> ********************************************
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20140528/3bf7d587/attachment.htm

More information about the Bf-docboard mailing list