Hey- Christopher Schmidt wrote: > 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 think there is a lot of sense in organizing ideas. Not that we would commit ourselves to an outline for eternity, but it is nice to have a sense of what you hope people to write before tasking them with writing. I like the look of the "Official documentation" outline - though I would resist getting really specific at this point. I think this is probably what Chris is saying as well. If there is other documentation out there that people find particularly effective - preferably documentation for software of somewhat similar scope - it would be good extract a general outline from that. The nice thing about having some general agreement about the structure of the docs would be that people could accept tasks for writing individual parts. Tim > 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, -- Tim Schaub OpenGeo - http://opengeo.org Expert service straight from the developers. _______________________________________________ Dev mailing list [email protected] http://openlayers.org/mailman/listinfo/dev
