As for instructions -- it's somewhat depends. Sometimes instructions work, sometimes they don't We still have users who followed those instructions and had issues getting manual fully built. Surely it's something caused by a particular setup on that machine, but it is just wrong claiming that everything works just fine and leaving contributors all alone with those issues.
Julien, i recon it bullshit to wait 30min for the manual to be compiled when you only need to fix single typo. Surely you can commit stuff directly without local check, but that's only asking for even bigger problems. Brecht, Thomas, the quality of those docs are not increased by Sphinx itself, it's just because people invested fewzillion effort to re-do manual from scratch. Same could have been easily done with existing Wiki manual. Dan, i bet we can configure new wiki in the way it works reliable and fast enough. If we have strong coordination work happening around documentation, i do not see any reason to commit to any global changes and diverge things and raise the entry barrier any further. That coordination could easily happen inside of wiki (assuming it gets re-installed and updated to all latest versions of everything and cleaned up all the configs). On Sat, Feb 27, 2016 at 11:46 PM, Julian Eisel <eiseljul...@gmail.com> wrote: > Spent some time thinking about this (wiki vs Sphinx) and after all I > agree with Brecht & Thomas as well. > > On a first look, the instructions for building the manual might make > the appearance as if there was quite some work needed, but this really > isn't the case. It's mostly a matter of copy-pasting 3-6 commands > (including cd commands). > Don't remember how long the build time was, but I doubt it would take > anyone longer than ~30 mins to get everything set up. > Again I think it is much easier than it may seem. Maybe some video > tutorials could illustrate this a bit better. > > Sphinx isn't no magic bullet, but I don't think wiki is either. And > regardless of the amount of individual contributors, I think the > manual is in a pretty good shape now :) > > Just my two cents. > > Cheers, > - Julian - > > On 27 February 2016 at 23:35, Dan McGrath <danmcgrath...@gmail.com> wrote: > > Lets not forget the fact that the new manual ultimately is a bunch of > plain > > html (well, not all, but static at least) files here, no php to crash, > > hack, upgrade blah blah. Speed-wise, it's hard to beat the performance > for > > this type of setup. > > > > Dan > > > > On Sat, Feb 27, 2016 at 4:52 PM Thomas Dinges <blen...@dingto.org> > wrote: > > > >> I agree with Brecht here. > >> > >> The entry barrier is a bit technical, agreed. But following the steps on > >> how to set it up in the Manual, it was a 5 minute job. > >> After that it's not difficult anymore. Visually the new manual is much > >> better and well structured, I missed that in the old wiki. > >> > >> Best regards, > >> Thomas > >> > >> Am 27.02.2016 um 22:48 schrieb Brecht Van Lommel: > >> > I'm a bit surprised that the manual is coming up as an issue now, > >> > there's been a lot of good work done there in the past few months. > >> > > >> > Even if it's just a few people doing most of the work, in my opinion > >> > that's just how most open source projects work. A small dedicated core > >> > and then smaller contributions from other. And I see commits from > >> > developers like Bastien, Thomas, Dalai, Gaia, Julian, Tamito and > >> > contributions from other people too. I don't think the wiki manual was > >> > more active? > >> > > >> > It would be good if the barrier could be lowered, maybe including > >> > sphinx python modules in the svn report, a Blender addon to help, I > >> > don't know. And certainly I would like all developers to document > >> > their work in the manual directly. > >> > > >> > But in my opinion the result is already much better than what we had > >> > in the wiki, without so much wrong information, broken links, warnings > >> > about reorganizations that never happen, etc. > >> > > >> > > >> > > >> > On Sat, Feb 27, 2016 at 9:02 PM, Campbell Barton < > ideasma...@gmail.com> > >> wrote: > >> >> On Sun, Feb 28, 2016 at 2:45 AM, Sergey Sharybin < > sergey....@gmail.com> > >> wrote: > >> >>> So the actual issue is a lack of coordination work for contributors > >> and the > >> >>> reason why Manual is still in a reasonable shape is simply only > >> because all > >> >>> the contributors are scared away and now it's 1.5 people only > working > >> on it. > >> >> The changes that have been made had some review first and corrections > >> >> made before being committed. > >> >> > >> >>> f we'll do better coordination work, then Wiki documentation will > not > >> be a > >> >>> disaster at all. > >> >> Maybe so, on the other hand the wiki had a long time to prove its > self, > >> >> and after many years never gave very usable documentation. > >> >> > >> >> I think we just don't have enough people interested and capable to > >> >> write (and more importantly maintain) documentation on *any* system. > >> >> > >> >> At this point though the new manual seems to be so unpopular that > >> >> (even though I personally find it nice to work with). > >> >> > >> >> This seems strange since for Blender we have 4gig of libs, or > >> >> install_deps scripts... boost, > >> >> yet for documentation installing a Python package is unacceptable or > so. > >> >> Almost nobody (close to none of the developers) is really interested > >> >> to even bother installing Sphinx and trying to use it. > >> >> > >> >> Can we just give up and declare ourselves incapable of maintaining > >> >> documentation entirely? > >> >> Move back to the wiki? leave existing docs to bit-rot? > >> >> > >> >> If there is no support for the current system, > >> >> I'm not sure if we can expect anything to improve. > >> >> _______________________________________________ > >> >> Bf-committers mailing list > >> >> Bf-committers@blender.org > >> >> http://lists.blender.org/mailman/listinfo/bf-committers > >> > _______________________________________________ > >> > Bf-committers mailing list > >> > Bf-committers@blender.org > >> > http://lists.blender.org/mailman/listinfo/bf-committers > >> > >> _______________________________________________ > >> Bf-committers mailing list > >> Bf-committers@blender.org > >> http://lists.blender.org/mailman/listinfo/bf-committers > >> > > _______________________________________________ > > Bf-committers mailing list > > Bf-committers@blender.org > > http://lists.blender.org/mailman/listinfo/bf-committers > _______________________________________________ > Bf-committers mailing list > Bf-committers@blender.org > http://lists.blender.org/mailman/listinfo/bf-committers > -- With best regards, Sergey Sharybin _______________________________________________ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
