On Thu, 31 Oct 2013 22:22:04 +0000 Andrew F <andrewfriedman...@gmail.com> said:
there is no chance we can compete with qt docs. not on the coldest day in hell will it freeze over. qt literally has a whole pile of DEDICATED documentation people paid fulltime... and have been paid fulltime for many years. we have zero. doing documentation for us means NOT adding features developers need/want. it means not optimizing things to be faster that developers want (and that competing toolkits keep doing too). it means not reviewing patches that come in. it means not fixing bugs that exist. it basically means not doing code. it's a choice of using an existing resource for something else. let me give you an example on how much work it takes to do docs. http://git.enlightenment.org/core/elementary.git/commit/?id=37fe9cc77144fe42e054a082ed58a4c52a961d35 specifically look at the docs i wrote in the header. those very basic docs took about as long to write as the code itself. writing docs is a time-consuming effort. going beyond the docs i wrote there to write up a dialog on the reasoning for those api's, several examples, and so on will blow out the time needed even more. it's all a matter of time. unless we get a massive community effort behind writing lots of documentation we're not going to go very far and the code will be the thing that suffers. to say that efl is not documented is wrong. http://www.enlightenment.org/p.php?p=docs saying that it could be better - sure. but how much effort for how much gain? just talking efl here. not e17/18 internal code and other apps. my current count for api's in efl + elm is 6350 or so. that's NOT including all the enums, structs etc. so let's make that an even 7000 if we throw all of those in shall we?. "good" documentation might average 2 pages of printed text per api (7000). that means not just the description and prototype but also reasoning, usage examples, diagrams, etc. so that's 14000 pages of documentation. that's 114 copies of war and peace. by all accounts it took tolstoy about 6 years to write it. that would mean we need 684 MAN YEARS of effort to write up what people see as "good documentation" for efl in its current state. so let's say we want to get this done... we need about $54 million to hire all the writers... :) and that's just documenting all the elements of efl (api's) - it's not writing all the introductions, overviews and associated docs that glue these together. so let's round that up to 800 man years then. that's $64 millon... (assuming average salary of a writer would be $80k/year including all overheads). just saying... it's a LOT of work... and it's not cheap. this simply can't be done without a majorly large lump of money or a massively distributed community effort. > enlightenment desktop is getting a lot of attention with e17. Good Speed, > good looks, and great features. > Maybe its time we step back and look at where we are going and what that > means. If Enlightenment is going big time, we are going to have more > qualified programmers join the project and they deserve to have decent > documentation. After all, why should we make it harder for them to get up > to speed. If they are joining the project, lets make it as easy as > possible. > > S > strong > documentation to strengthen the project. > P > erhaps we can brake the information up into logical chapters and have > different people or teams of people write specific chapters. > > Look at QT, they are getting huge and their documentation is exceptional. > Its easy for developers to get up to speed. Their success is directly > related to how easy it is to learn to program QT. > I think we should follow that model to help e17 grow even faster. > > We need an editor to outline the document, create the table of contents and > manage volunteers who will write the individual chapters. > > Who has the knowledge of e17 to do this? > > > On Thu, Oct 31, 2013 at 2:49 PM, Carsten Haitzler <ras...@rasterman.com>wrote: > > > On Thu, 31 Oct 2013 09:02:04 -0300 Vinícius dos Santos Oliveira > > <vini.ipsma...@gmail.com> said: > > > > > Em Qui, 2013-10-31 às 08:51 +0900, Carsten Haitzler escreveu: > > > > > > > i know. i spent some of my early life on unix/linux paying large sums > > > > for > > > > o'reilly books. and reading them cover to cover. they had diagrams. i > > > > frankly > > > > far prefer raw simple code over those books. the code is digestible in > > > > a > > > > fraction of the time. :) if i have an actual working bit of code i can > > > > compile > > > > it, run it and then modify it to see how it wobbles when poked. poke a > > > > bit more > > > > and see some more wobbling. these wobbles tell me the story of how > > > > CHANGES to > > > > the example affect the behaviour. start small with small changes and > > > > see. :) a > > > > book doesn't give me that. english words don't give me that. code > > > > does. :) but > > > > that is my style - i know that within all fields of education > > > > including foreign > > > > languages, math, science, etc. etc. i always gravitated to "learn by > > > > example". > > > > i naturally break up the examples into their constituent parts and > > > > know how to > > > > manipulate them - the pattern builds over time naturally. > > > > > > > > > Code is interactive. School and all non-interactive shit is difficult > > > and pain to learn (at least for me and for you). > > > > > > But... I wonder how you avoid undefined behaviour code that can break in > > > the next release of the lib/compiler or in the second compiler/platform. > > > > experience teaches... and of course reading docs/references. > > > > -- > > ------------- Codito, ergo sum - "I code, therefore I am" -------------- > > The Rasterman (Carsten Haitzler) ras...@rasterman.com > > > > > > > > ------------------------------------------------------------------------------ > > Android is increasing in popularity, but the open development platform that > > developers love is also attractive to malware creators. Download this white > > paper to learn more about secure code signing practices that can help keep > > Android apps secure. > > http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk > > _______________________________________________ > > enlightenment-devel mailing list > > enlightenment-devel@lists.sourceforge.net > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > > ------------------------------------------------------------------------------ > Android is increasing in popularity, but the open development platform that > developers love is also attractive to malware creators. Download this white > paper to learn more about secure code signing practices that can help keep > Android apps secure. > http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk > _______________________________________________ > enlightenment-devel mailing list > enlightenment-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ Android is increasing in popularity, but the open development platform that developers love is also attractive to malware creators. Download this white paper to learn more about secure code signing practices that can help keep Android apps secure. http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
