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" <[email protected]> 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. _______________________________________________ Development mailing list [email protected] http://lists.qt-project.org/mailman/listinfo/development
