On Mon, 12 Oct 2015 11:52:56 -0700 Cedric BAIL <[email protected]> said:
> On Wed, Oct 7, 2015 at 7:58 PM, Carsten Haitzler <[email protected]> wrote: > > On Wed, 07 Oct 2015 18:07:50 +0000 Mike Blumenkrantz > > <[email protected]> said: > >> On Wed, Oct 7, 2015 at 1:58 PM Davide Andreoli <[email protected]> > >> wrote: > >> > 2015-10-07 4:52 GMT+02:00 Jean-Philippe ANDRÉ <[email protected]>: > >> > > jpeg pushed a commit to branch master. > >> > > > >> > http://git.enlightenment.org/core/efl.git/commit/?id=12f9fea2a4d4d641a09fd6563a83b925d62e4868 > >> > > > >> > > commit 12f9fea2a4d4d641a09fd6563a83b925d62e4868 > >> > > Author: Jean-Philippe Andre <[email protected]> > >> > > Date: Fri Oct 2 18:14:25 2015 +0900 > >> > > > >> > > EDC Doc: Some fixes > >> > > > >> > > We need to move this doc to the wiki and complete it :) > >> > > > >> > > >> > Moving the edcref to the wiki means that people cannot have it offline, > >> > and I'm quite sure no devs will update the wiki after a change in the > >> > code. So I'm quite against this idea > >> > > >> > >> While I am not disagreeing that edc documentation could use improvements, I > >> agree with keeping it in the source. We are not good at > >> maintaining/updating in-source documentation, but we are even worse at > >> anything not directly in the source tree. > > > > but then only "we" can edit docs. no one else can help or pitch in. the wiki > > allows for discussions and editing by a far wider audience. it also happens > > to be in git. :) > > I may be on a loop on this, but I don't see reference documentation > being written by anyone but dev. Look at the activity of our current > wiki. People can easily contribute tutorial and guide, but it is still > only developers involved in EFL who do so for a very large majority of > the content (Above 90% of the content easily). I would love to be > wrong here, but I think it is still more productive to keep the > documentation in front of the developers eyes or it will just never be > up to date. history proves that this doesn't work. devs wrote NO DOCS effectively until someone was paid to do so by contract. don't kid yourself here. also writing docs with doxygen takes forever because you cannot SEE your results for multiple minutes. run "make doc" and wait... and wait ... and wait... and wait... i once spent a day trying to clean up our docs to fix up links so docs can be found (that otherwise are not linked or findable) etc. and i frankly just gave up. it was an insane time-sink with minimal results. there is also another good reason to do this. and it's structural. reality is that our biggest user of efl is samsung and the last time there was a doc drive, the docs had to be written against efl 1.7 which at the time was 2years old and a split tree. and so those responsible were given the tarballs/trees and told to write against that. this of course resulted in the docs being mostly useless because patches were against such old code that it'd almost pointless to deal with it. putting docs in a single central place is trying to avoid this happening again. docs have to be worked on against the "current state" to be worked on. this makes work useful rather than throw-away. elementary will eventually merge into efl - the next time this kind of thing happens history will repeat itself ... again. unless we do something to change it. -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) [email protected] ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
