[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [E-devel] Efl High level documentation

kkapelon@freemail.gr wrote:
I have seen the developer docs for Enlightenment.
I know that they are behind the latest code and I am not going
to moan about it. Programmers always like to write code more than docs.

However there is not any high level documentation. I mean documentation which describes the concepts of efl.
Most people think (I may be mistaken) that efl is another
toolkit like gtk+ or qt. Of course this is not true.

The most important points are in my opinion the fact that evas knows the "state" of the canvas and the fact that making an application
edje themable completely separates logic (code) with looks (theme).

I think that this kind of documentation will draw interested programmers
to efl who at the moment dismiss it, thinking that they should stick with gtk+/qt.

Is there any interest about this?
I am asking because I would like to start this kind of documentation.

Sorry for being so late to the party.

The closest thing we have to such a beast atm is the EFL Cookbook. The first chapter is a sort of high level overview of sorts, and then in the intro to each chapter there is a "Intro to..." In the past I'd considered creating a high level standalone document but it was unpractical imho, basically everything in it belonged on the website, so I just did that. That left individual breakout manuals for specific topics, the Edje Book and EWL Book were created, followed by an EFL general book for topics that didn't really warrant a full book of their own, which morphed into the EFL Cookbook.

The docs in general need a major overhaul. The EFL Cookbook needs an end-to-end scrubbing, the EdjeBook is almost entirely useless, and the Doxygen could use an editors eyes. Additionally, the website, which I think should be the pivotal source of information, is a complete disaster and in need of help.

Personal time constraints (read: OpenSolaris) are keeping me from getting a lot of what I want to do from getting done. As far as docs go, the EFL Cookbook is still open for anyone to contribute to. Other additional docs are welcome, I'm certainly turning nothing away. A high level book, if written well, would be a welcome edition to the E/EFL bookshelf. In addition to just this, it'd be nice to roll the Get-E docs into a proper document (DB XML) and add it to the official doc set, as well as expand it as need be. Depending on the success of that document, more user-level documentation might be appropriate. When E17 releases I'd like people to have something to plop down in their laps when they explore the features and functionality of E, from a new users perspective. Lots of pretty pictures, that sort of thing. If nothing else it would add a real professional feel to the release, I think.

So there is plenty to do. There is no such things as too much documentation... there is such a thing as bad documentation, but we do what we can. ;)

I appreciate you using DB XML. I've got makefiles in the existing document sources (found in CVS, e17/docs/) which you might want to use to keep things consistent. If there is any way I can help please don't hesitate to ask.