On Sun, Feb 28, 2016 at 10:27 AM, Sergey Sharybin <[email protected]> wrote: > 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. >
Is this happening often? is this on IRC... mailing list? > > 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. Full build here takes 1min, 32seconds (on system from 2009). Further partial rebuilds are a few seconds. And if your *really* only fixing typos, you can just commit too. > 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. Manual is definitely not redone from scratch. > 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 <[email protected]> > 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 <[email protected]> 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 <[email protected]> >> 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 < >> [email protected]> >> >> wrote: >> >> >> On Sun, Feb 28, 2016 at 2:45 AM, Sergey Sharybin < >> [email protected]> >> >> 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 >> >> >> [email protected] >> >> >> http://lists.blender.org/mailman/listinfo/bf-committers >> >> > _______________________________________________ >> >> > Bf-committers mailing list >> >> > [email protected] >> >> > http://lists.blender.org/mailman/listinfo/bf-committers >> >> >> >> _______________________________________________ >> >> Bf-committers mailing list >> >> [email protected] >> >> http://lists.blender.org/mailman/listinfo/bf-committers >> >> >> > _______________________________________________ >> > Bf-committers mailing list >> > [email protected] >> > http://lists.blender.org/mailman/listinfo/bf-committers >> _______________________________________________ >> Bf-committers mailing list >> [email protected] >> http://lists.blender.org/mailman/listinfo/bf-committers >> > > > > -- > With best regards, Sergey Sharybin > _______________________________________________ > Bf-committers mailing list > [email protected] > http://lists.blender.org/mailman/listinfo/bf-committers -- - Campbell _______________________________________________ Bf-committers mailing list [email protected] http://lists.blender.org/mailman/listinfo/bf-committers
