On Mon, Nov 24, 2008 at 08:36:40PM +0100, Yves Jacolin (free) wrote: > Following the first steps Chris made few weeks ago, I would like to propose > some though about documentation. As wiki and svn documentation are > complementary, the first one will be a kind of quick write documentation. The > svn one will be more structured. > > http://trac.openlayers.org/wiki/proposDoc
Yves, My feeling on this is that the first step is to concentrate on getting the documentation written. Once we have the documentation written, it becomes a lot easier to organize it -- trying to do so ahead of time may be a bit premature. (Why organize what you don't yet have?) I would say that in general, it probably makes sense, as much as possible, to strive for a single set of reference documentation -- in the same way that a book would be organized. This means that "Howto"s seperate from other docs mya not make the most sense -- instead, these things should be slotted in where they fit. Also, rather than have seperate trees for different langauges, in my mind, we should just have the links to seperate language translations alongside english links, though how exactly to do that remains to be seen. Additionally, I don't think that we should plan on maintaining *any* long term documentation -- that is, documentation that we expect to maintain as the public face to users -- in the wiki. Instead, we should migrate this information into the 'official' documentatino as we see it is stable enough to be maintained, and keepin things up in the wiki should be discouraged. As we see more of the 'official documentation' take shape, we can see if I'm totally out of line, but personally, I think that the wiki should be for notes -- and that as we get things put together, we should build them into 'official' documentatino as soon as they've taken serious shape. > I have some contents in french for the second part (first chapters) which I > can translate it in english (but realy need to be corrected by a native > english writer ;) ). I'm totally willing to do so. Let me know when you're far enough along that you're looking for feedback. Regards, -- Christopher Schmidt MetaCarta _______________________________________________ Dev mailing list [email protected] http://openlayers.org/mailman/listinfo/dev
