[Development] Tizen conference - talk proposal: "There's an ~~app~~example for that"

[Jonas M. Gastal]

Bom, a exemplo, e pedido, do Antognolli estou compartilhando minha proposta de 
palestra. Naturalmente sugestões são muito bem vindas.

Author: "Jonas M. Gastal" <jgastal at profusion.mobi>
Team leader at ProFUSION Embedded Systems

Title:
There's an ~~app~~example for that

Short bio:
Gastal has been a professional Linux developer for approximately 5 years, 
having worked with a multitude of different technologies and with upstream 
communities he has unique insights into what drives usage of these 
technologies. At ProFUSION for a little over two years he has worked on 
numerous Enlightenment Foundation Libraries(EFL) related projects, most 
interestingly he was technical lead in both documentation efforts by the EFL 
community, one conducted last year and one just starting.

Short abstract:
The presentation hits three main aspects: what documentation we have, what 
virtues makes documentation good and how to improve documentation. The 
presentation will start by showing the scope of the currently existing EFL 
documentation, showing the extent of the existing API reference as well as the 
existing examples. Then while touring the documentation a few particularly 
interesting examples will be talked about in detail and what makes them 
interesting will be discussed, thus giving a starting point to talk about what 
are the virtues of good documentation. Then the presentation shifts gears to 
show how to create a well documented example using the previous discussion to 
base it. This will include the entire process of creating a good example, from 
the very start of deciding what to exemplify through writing the code and 
explanations to the final steps of submitting the example upstream and dealing 
with the community.

Abstract:
The presentation has three main goals: to show that the EFL has good 
documentation, to instill in the audience the basic principles of what makes 
good documentation and to make the basic principles clear by demonstrating how 
to create a good example. The scope of existing documentation will be shown 
with a quick tour of the API references and examples that we have for Eina, 
Ecore, Evas and Elementary. Then a couple of the elementary examples will be 
highlighted and its virtues pointed out and briefly discussed. With that basis 
an example is then created putting to practice the discussed issues.

Before diving into the documentation a few stats about the documentation are 
presented, these stats aim to impress on the audience just how large the 
documentation of the EFL currently is, but since quantity is of no use without 
quality, the quality of the existing documentation is demonstrated with a tour 
of it. The tour starts at the base of the EFL, Eina, where both data 
structures and some string utilities will be shown, then moving on Evas' and 
Ecore's documentations are both explored simultaneously through some simple 
graphics application examples. Lastly in the tour is Elementary which has 
several of it's widget examples presented.

Still focusing on the shown examples of elementary it's possible to move the 
discussion to some of the virtues of good documentation: clarity, conciseness 
and real world relevance. Once enumerated an exploration of the relevance of 
these attributes starts with the pointing out of them in the existing 
documentation and how they contribute to making it good and in what situations 
are compromises necessary.

The discussion of the virtues of good documentation is made more concrete with 
the walk-through of creating an example. This walk-through consists of several 
steps which will be briefly talked about and then demonstrated concretely, 
leaving us with a true example at the conclusion. The steps are:
 - Identifying a topic to be documented;
 - Defining the objectives of the documentation;
 - Creating a simple and concise example program that exercises the topic;
 - Creating an explanation for the relevant parts of the example;
 - Polishing;
 - Submitting the documentation upstream;
 - Interacting with the community to make sure the submission is accepted.
With the complete documentation of this topic constructed the presentation 
concludes with a call to arms pointing out that there is still a lot of work 
to be done in improving the EFL documentation, that contributing documentation 
is a great starting point in getting involved in the community(especially if 
coding seems threatening) and opening up the space for questions.