On Monday 2002-07-08 17:30 +0100, Gervase Markham wrote: > > * I don't think we want a low barrier to entry. We want documentation > > to be written by people who know what they're talking about, namely, > > the developers. The developers know how to use CVS, so it's one > > fewer thing to learn. > > "The developers" have had several years to produce decent > documentation for Mozilla. With a couple of shining exceptions, it > hasn't worked.
So is the solution to try to get the developers to write documentation (which would likely be good documentation if they wrote it), or to try to get people who would write incorrect and misleading documentation to write the documentation? Pretty much everybody who knows enough to write developer documentation is a developer. > The current website is a complete disaster in terms of finding what > you want (good way to tell: people use Google to search it rather than > attempt to use our navigation.) It is? I'm usually able to find what I want among the existing documentation. When I can't, it's usually because the document in question isn't listed in any indices at all. That's a problem that won't be helped by a different structure -- some people still will not bother adding their documents to the indices. Are these problems you mention because people are looking for documentation that doesn't exist? Better organization won't help anyone find that. > This is not a point in Zope vs. CVS - it's merely an observation. The > current system of producing documentation does not work. What do you > suggest? I suggest encouraging the people who should be writing documentation to write it, and once they've written it, to share it. I think the most successful group at getting people to write documentation is the organizers of the Monday night techtalks at Netscape, which have led to a bunch of good techtalks with useful slides that often end up online (and eventually videos too, if they ever get posted). See http://mozilla.org/newlayout/doc/ for the layout-engine-related talks. (The people who have given these talks could perhaps use a little more encouragement to get their slides online outside the Netscape firewall, though. Perhaps I should try to do that for more than just the ones that belong on the layout docs page...) > > * What kind of discussion do you want? How would it be useful? > > See later replies; I also believe that an annotative model for pages > leads to documents which are far more useful, with less effort on the > part of the author (because he doesn't need to update them so often.) As an author of docs, I don't think that would be true. The total number of email messages I've received about all of the docs and doc indices I've written is probably under ten -- not at all hard to keep track of or reply to or deal with immediately. With that frequency of comments, I probably wouldn't bother checking for annotations more than once a year, so it would just slow down the feedback loop. I don't think we should try to find a way to help us handle the problem of too much feedback until we're actually facing the problem of too much feedback (which doesn't seem likely to happen soon). -David -- L. David Baron <URL: http://www.people.fas.harvard.edu/~dbaron/ >
