On Wed, Oct 30, 2013 at 1:02 PM, Robert Heller <hel...@deepsoft.com> wrote:
> At Wed, 30 Oct 2013 12:09:52 -0400 Enlightenment users discussion & > support <enlightenment-users@lists.sourceforge.net> wrote: > > > > > Hi, > > > > Just to chime in with 10c's worth. > > > > This is my personal preference, working examples atleast as a base works > > for me ( examples as in code )... Documentaions words are ok for the > nitty > > gritty but not as a substitute for a good example. > > > > If you look at most tech books, the question is how many of us read any > of > > them cover to cover?. > > But *I* do find them *very* useful, even if I don't read them cover to > cover. > Often reading a page here or there (or even a whole section) if *very* > useful, > and *not* because of the included examples. And an *important* part of > any > tech book is its index and/or table of contents -- either/both of these > gets > me to the page or section I need to read. > Fair comment, > > > > > Probably near none at all, so really for me thats enough said. > > > > The main problem with documentation-by-example is what happens when there > isn't an example that covers the question at hand? Or (worse) when the > example's name or title does not fully suggest or explain what it is an > example of. Also, sometimes it is critical when looking at examples that > there > is some explaination of the concepts involved. Examples alone can never > really > explain how to do things, if the *underlying* concepts are not either > known or > else explained. For example, what does 'swallow' mean in the context of > edje? > The code in e_menu is using this, but I have no clue as to what is going on > and the swallow example does not really *explain* what is going on, it just > shows you how to use it, without explaining why you would do it or what > its purpose is. Somehow, I don't think it has anything to do with eating or > birds (but maybe it does?). > > I think at this stage, perhaps it would be good to take the opportunity to take a look at the documentation available. Alot of these comments though have been made on howto's, in that they usually only made sense after you have completed the task yourself. I would not doubt that the current documents could use some work. I am not actually 100% on whom would be doing the task. Possibly the person who wrote / contributed to the module in question. Would be cool to find a common agreement here. Nige > > > Nige > > > > Disclaimer: This is my personal belief as stated. > > > > > > On Wed, Oct 30, 2013 at 11:58 AM, Vinícius dos Santos Oliveira < > > vini.ipsma...@gmail.com> wrote: > > > > > Em Qui, 2013-10-31 às 00:48 +0900, Carsten Haitzler escreveu: > > > > > > > this is simply a matter of time. spend 1hr adding a feature someone > > > > wants, or 1 > > > > hr writing docs. > > > > > > > > > Documentation is a feature too. > > > > > > > > > > i personally use docs as reference only - i ALWAYS use example > > > > codee. nothing to do with java - it simply is faster, easier and more > > > > practical. > > > > > > > > > Documentation can include snippets. > > > > > > > > > > i read unix man pages to begin with and frankly they told me very > > > > little at all. a whole tonne of words for very little use. examples > > > > taught me > > > > 100x more in the same amount of effort with docs backing it up as > > > > reference. > > > > > > > > > Comparing manpages with HTML rich (or even PDFs) docs. > > > > > > > > > * Manpages cannot have images (maybe with Terminology this is no > > > longer true) and for a GUI toolkit this is kind of a must. > > > * Manpages don't have an easily browsable content (like HTML) > have > > > > > > * Summary > > > * Detailed description and extra sections > > > * Extra pages (not directly related to one class only) > > > * A small text for each function > > > > > > > > > > > > > as such most of efl does have docs. they are not voluminous essays. > > > > again - a > > > > matter of time. if you wish to contribute by writing voluminous > docs.. > > > > go for > > > > it. :) > > > > > > > > > The magic of open source. :) > > > > > > > > > -- > > > Vinícius dos Santos Oliveira > > > https://about.me/vinipsmaker > > > > > > > > > > ------------------------------------------------------------------------------ > > > 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-users mailing list > > > enlightenment-users@lists.sourceforge.net > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-users > > > > > > > > > > > > -- > Robert Heller -- 978-544-6933 / hel...@deepsoft.com > Deepwoods Software -- http://www.deepsoft.com/ > () ascii ribbon campaign -- against html e-mail > /\ www.asciiribbon.org -- against proprietary attachments > > > > > > > ------------------------------------------------------------------------------ > 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-users mailing list > enlightenment-users@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/enlightenment-users > > -- “Science is a differential equation. Religion is a boundary condition.” Alan Turing ------------------------------------------------------------------------------ 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-users mailing list enlightenment-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-users
