On 3/7/06, Brad O'Hearne <[EMAIL PROTECTED]> wrote: > I'll reiterate: you cannot document accurately and completely if you > don't know the full scope of feature, which is clearly locked inside the > heads of a few developers.
It takes a lot longer to extract, but everything is in the open in code here, so I don't think this is entirely fair. > The web site doesn't even come close to > describing things to the point where someone could follow up with > documentation. Give me an example. > If I could document maven without having to spend months > upon months trying to elicit answers to questions and Googling the great > unknown for Maven 101 information, I probably would. It would take months and months to document, but if you take small chunks you are concerned with, you'll find someone will take time to explain it to you in a way that can be done very quickly. If you toss that in the wiki, someone still needs to come and organise that information, but its a start. We're all suffering the same problem - knowing where to start. > As it is, I'm about > a gnat's eyebrow away from writing my own custom alternative to maven. And how much of a time pit will that be? Although you'll start small, there's probably 3-4 man years of development in just the current version of Maven (if not more), and that's if you learn all the lessons from the products that come before it. Still seem like a good idea? :) > It doesn't compute -- for the great product maven is, the lack of > documentation has turned the experience into a huge time pit. Every > problem is a new plugin and a new configuration option or file and a new > frontier of undocumented stuff, and a whole new cycle of trial and error. And again, *we know* and are trying to correct it. And trying to deal with other stuff like fixing bugs, applying patches, not to mention actual jobs and a real life away from the computer. If we dropped everything and wrote docs for 6 months, people would complain their bugs haven't been fixed or the features they want aren't being done, that releases aren't cut and that questions aren't answered. We're honestly trying to find a balance, and more volunteers are always welcome. As you said, this isn't directed at anyone here specifically, because it happens all the time, so let's do some math with some totally made up numbers: Amount of time spent researching problem: 2h Amount of time spent emailing dev list about the importance of documentation: 1h Net effect on documentation: 0 (Nobody dropped everything and started writing because they suddenly realised it was necessary, they already knew). Now, let's say this happens: Amount of time spent researching problem: 2h Amount of time spent emailing dev list about missing documentation: 15min Net effect on documentation: 15 min Sure, you don't do this every time. But imagine the net effect on documentation we'd have if everyone that wrote these sorts of mails, or answered a duplicate question wrote it down and put it in the wiki. And then one person, who can be a developer, or other volunteer, came and started organising the wiki content where they couldn't before contribute to the docs. As a community the net effect of the first option is largely negative. More than one person is reading and replying to these mails - less time on something else. 15 minutes on a rough description of something you just found out saves someone else 2 hours of work. Unfortunately, there aren't a lot of people willing to do this. > Let's call it what it is -- the lack of > documentation is just cutting corners. Its trading away completeness, > and excellence in a project for what is fun, and/or what we aren't > willing to wait for. Agreed, to some extent. But there are equally important things (like fixing bugs and getting out and having a life) that I'd not like to cut the corners of. I rarely work on what is fun these days. While I enjoy it, I drive what I do entirely by priority/time to complete ratios. > Whatever is worth doing, is worth doing well. Couldn't agree more. Anyway, that's my own little 'rant'. Back to documentation (and yes, that's what did get interrupted by this thread). - Brett --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
