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