[Bf-docboard] Documentation status and upgrade proposal

[Howard Trickey]

I would prefer a system where images are in git too.
A mixed workflow where images go in svn and everything else goes in
git would put a barrier to adding images that would, I think, tend
to have writers not bother sometimes putting helpful images in.

Yes, I know the concerns about binary sizes, but maybe one could estimate
this effect by adding up sizes of current images in the manual,
and perhaps decide that it is acceptable.



On Tue, May 6, 2014 at 1: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/04796d5a/attachment.htm