At Wed, 30 Oct 2013 12:09:52 -0400 Enlightenment users discussion & support
<enlightenment-us...@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.
>
> 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?).
> 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-us...@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-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
