[Bf-docboard] Documentation status and upgrade proposal

[Jonathan Williamson]

This looks very promising! +1

Jonathan Williamson
http://cgcookie.com


On Tue, May 6, 2014 at 12:59 PM, Bastien Montagne <montagne29 at wanadoo.fr>wrote:

> +1 for sphinx.
>
> I always had the feeling mediawiki was not really suited for a manual
> (though some tremendous time was spent trying to make a bit more suited
> some years ago). And I do not see the "easy to edit" thing as a wiki big
> pro in our case (this tends to make editors way too much volatile, which
> is not good in a manual context)…
>
> Just my two cents. :)
>
> Bastien
> On 06/05/2014 19:34, Campbell Barton wrote:
> > Hi, I wasn't aware of this list existing, but I was involved with the
> > proposal to move the manual to a new system, will give some replies.
> >
> >
> >
> > @brita
> >
> >> Besides Manual, Dev and Tutorial also fit well in this scheme.
> > Not sure about this. Probably we can leave tutorials to other web
> > sites (there are many), and Dev docs Im happy to keep on wiki for now.
> > Since they fit the scheme of random-linked-pages, much better. (as in
> > - they dont need to read so much like a book).
> >
> > On the other hand, if this system works well, Im not totally against
> > moving other parts of our wiki to it, But suggest to hold off until
> > the manual has proven to be a success.
> >
> >
> >
> > @Jeffrey H
> >
> > Not sure what you mean about "linking" RestructuredText has a fairly
> > nice method to add in cross-references and you can link to external
> > sites too, I don't see this as an issue.
> >
> > but agree "user contributions" is a concern. There is the idea that
> > making user contributions `easy` is the best way to get a document
> > done,
> >
> > But IMHO the flip side of this --- is you get a lot of half edited
> > pages, people start pages and dont finish them, and we get edits that
> > probably should be reviewed or even rejected because of poor quality.
> > Not to say editing documentation should be made difficult, just that
> > the current wiki system has _not_ given us a really great manual IMHO
> > (though parts of it are great of course).
> >
> > Currently we have a situation where docs are *broken* and thats
> > considered normal, I think with a better system authors can be in a
> > bit more control and not just have random 2.4x pages mixed in with
> > 2.5x, 2.6x, 2.7x docs.
> > However at the end of this day this is still work someone has to do,
> > our-millage-may-vary :)
> >
> > Eventually I would like that the manual is a complete-document,
> > covering areas of Blender in a clear & concise way, if something is
> > incorrect or missing, this is reported as a bug/issue,
> > it gets fixed before release, and we have some valuable resources we
> > can include with Blender - basically manage this closer to how we
> > manage Blender source code and releases.
> >
> > Your last point about using a wiki to supplement is well taken, but I
> > dont think its unique to wiki's --- the manual can link to any
> > external resource when it makes sense to.
> >
> >
> >
> > @marco ardito
> >
> > re - contributions, right, users can prepare docs on a wiki, on
> > github, anywhere... then submit for inclusion.
> > Since this is just a directory of files we're not locked into one way
> > of doing things.
> > For the Python API docs, sometimes I've just got mails containing
> > improvements, but Id like if we had something a bit nicer.
> >
> > Expecting documentation authors to use git may be unrealistic, however
> > github does have a way to edit text online and commit (without having
> > to install git locally).
> >
> > Note that we aren't locked into git, if we find some other system
> > better for authors, we can move to that too.
> >
> >
> > Your point about a manual not just being a reference is important,
> > some wiki pages in our current manual - list every button in a panel
> > with their tooltips,
> > In most cases i dont think this really helps, its not giving insights
> > into how things work or showing users why they might use certain
> > features.
> >
> > But I think this is orthogonal to which system is used, and am a bit
> > worried if we try to migrate the manual to a new system at the same
> > time as rewriting a lot, that it never gets finished.
> >
> >
> > As for translations, while there is no special support for it (which
> > could be nice to have), It could work out fine just to use branches,
> > translators can review commits made since they last translated and
> > update their versions if needed.
> >
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20140506/526ea45b/attachment.htm