Re: [e-users] [E-devel] Is there *real* documentation for edje?

[Carsten H. (T. R. <ra...@ra...>]

On Wed, 30 Oct 2013 22:05:06 +0200 Alan McKinnon <ala...@gm...> said:

> On 30/10/2013 21:42, Vinícius dos Santos Oliveira wrote:
> > Em Qua, 2013-10-30 às 13:43 -0400, Nigel Sollars escreveu:
> > 
> >> Would be cool to find a common agreement here.
> >>
> >> Nige
> > 
> > 
> > Like Rasterman said: It's an open source project. We can change the
> > project and if the contribution is useful, it'll go upstream.
> > 
> > But about "common agreement". This is not needed, because the options
> > don't exclude each other. We can have documentation AND examples.
> 
> 
> A comment from someone who mostly just lurks:
> 
> I see circumstances like this thread play out at work quite a lot, as
> the company grows and more heads join the dev teams, things diverge
> more. We since since stopped being a homogeneous team where everyone
> mostly thinks alike...  one thing keeps showing up:
> 
> Different people need different things.
> Everyone's headspace is wired differently.
> 
> I can't deal with examples and code snippets as documentation, stuff
> just doesn't hang together when that's what I have to work with. I also
> can't deal with endless lists of API functions (a-la javadoc), that
> doesn't tell me what it means. I need prose, descriptive paragraphs
> where the dev describes like in a conversation what they were trying to
> accomplish and how the design of a thing works. Give me that picture, I
> can figure out the detail. Give me just the detail and examples, I can't
> figure out the big picture.
> 
> That's how my head works. Robert's head seems to work similarly.
> Raster's head works completely differently.

sure. that's why i get baffled. for me an example is worth 1000 times its size
in prose. i see an example and i see a story. i see what can be and how it
hangs together - the inferences are right there. me - i read code like i would
read a book - it flows naturally to me and is by far more efficient in getting
across information. the docs are simply clarifications on some things examples
may not show, through tbh - if i have a new library... the FIRST thing i find
is it's header file and read. i mostly scan for api's, enums and structs. these
tend to give me a feel for how it works and then the example... and presto. in
this sense efl is more than adequate. it does this just fine.

but in terms of someone having written length prose on each and every aspect...
it does not. writing all that prose is a MAMMOTH task. seriously massive. it's
probably akin to at LEAST the effort involved in writing the code itself.
ESPECIALLY if you include diagrams/screenshots etc. basically it means, if you
wanted that, we'd have to stop all development for many many years and just
write documents.

as i said - it's a choice. i know i have chosen to march on fast as opposed to
write prose. hell - i have skipped enough other things too in the name of
getting more done - like "test suites". to be honest - i think we need test
suites MUCH MORE than we need prose. we need to be able to spot bugs,
regressions etc. sooner. efl is so big now that it is becoming an issue.

imho if the people who need and want prose (ie docs that read and flow like a
conversation), then as a project - those people should step up and write such
prose. that is in and of itself a very valuable contribution. we have a wiki
try try and help this process. it's where people could write articles about
small bits of efl they have come to understand the "hard way" and then explain
it in a prosey-style for others that like that. over time the wiki will fill
with vast nuggets of useful docs (prose). if it is managed well and
indexed/organized nicely it should work well. a bit of searching would let you
find relevant stuff. if you write an article - let everyone know. core devs can
read it and provide pointers (not the memory kind) - eg that some things may
actually be wrong or that some bits miss certain aspects etc. :)

> It may well be that Robert will have to write the docs he needs himself.
> That would be a good thing as there is a lack, he might be willing, and
> many folk would benefit.
> 
> My 2c.
> 
> And FWIW, I first used e17 about 8 years ago. I'm still trying to figure
> out what "swallow" means in this context as a verb!
> 
> -- 
> Alan McKinnon
> ala...@gm...
> 
> 
> ------------------------------------------------------------------------------
> 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
> enl...@li...
> https://lists.sourceforge.net/lists/listinfo/enlightenment-users
> 


-- 
------------- Codito, ergo sum - "I code, therefore I am" --------------
The Rasterman (Carsten Haitzler)    ra...@ra...