On Tue, 11 Nov 2008 15:23:21 -0200 andres <[EMAIL PROTECTED]> babbled:
> El Tuesday 11 November 2008 14:28:56 Lionel ORRY escribió: > > 2008/11/11 Stephane Bauland <[EMAIL PROTECTED]>: > > > Toma wrote: > > >> Ive always been a proponent of more docs and have always tried to make > > >> docs. Im down with it. > > >> > > >> The 0th step is creating a roadmap of what needs more documentation, > > >> what needs documentation revision, and how to organize all the > > >> documentation. > > > > > > I'm agree, the good way is to have a roadmap in trac, sure. > > > > > >> And instead of a 'team' as such, we could create a > > >> system where you just add a short blurb about a certain function then > > >> that gets added to a database... unless thats already possible? > > >> > > >> It would be good to keep it all on a wiki type setup, > > > > > > Imho, using something like docbook or another documentation's > > > format will be better, using this, it'll be more easy to provide > > > documentation in differents formats. > > > > Attached is an example of what can be done using AsciiDoc > > (http://www.methods.co.nz/asciidoc/index.html). The source file is a > > plain text file (the extension is .txt), and can generate docbook (see > > the pdf output using asciidoc + xsltproc + docbook-xsl-stylesheets + > > fop 0.95) of html (see the html output). > > > > It is easy to learn and to maintain. Moreover, a plain text file can > > be easily versioned through Subversion. > > > I just wanted to show some support for any kind of simple, plain text > documentation language like AsciiDoc or reStructuredtext. > > After using Docbook for more than a couple of months —with documents of > others and my own— I came to the conclusion that Docbook documents are > overcomplicated, unreadable, unmaintainable pieces of shit that I wouldn't > touch with a ten foot pole ever again. My experience with conversion tools > for Docbook was bad as well. i don't think going into a "document format" discussion is going to help when already we use javadoc in the source. right now libraries are in the sorest need for documenting. the api's we have are massive - and most of it undocumented. the documentation is in-line in the source right above the public function calls - there are many stubbed javadoc comment sections with "To De Documented" in them. :) this is probably the best place to begin - alll the not documented ones, document. then make sure all EAPI taggd functions/globals and other public header structs/enums have javadoc comments. once this is done we'll have a pretty good foot in the door for documents. next i'd say is quick start guides and tutorials on how to get started - this can be put in the source for each lib in a dummy .c file that only contains javadoc comments (nothing else). this .c file can just not be compiled, but kept in EXTRA_DIST - but this means the gendoc/make doc will nicely generatthe docs for that lib WITH the quick start/tutorial. for edje this can also include how to do .edc's and so on. i have no problem with having a doc team - i don't think just "Creating one" will do anything, BUT if there are people willing to put their hands up for it - i see no reason not to have the "official doc team" be them and let them have at it! -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) [EMAIL PROTECTED] ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
