I think docbook under version control satisfies these conditions. 1. After applying an xslt and creating html it is pretty easy to find stuff after google has its say (with help from good documentation evangelists who frequently link to relevant information while blogging about stuff; this is something nhibernate and spring seem to sorely lack; google cannot tell good information from bad information all on its own). 2. After applying an xslt and creating html the information is well ordered and you can skip around if you have any idea what you are looking for 3. there do exist editing environments for the docbook format, though there may very well be an easier to use format for raw text editing 4. source control does diffs well, so long as the editors play nicely this shouldn't be a problem; remember that everybody who potentially contributes or reviews will be a developer and should be expected to be able to understand a diff 5. this is more of a community issue; a mailing list seems to work well for managing patch contributions, whereas a login-requiring wiki brings a certain sense of exclusivity (esp for those of us who cannot seem to find the registration page) 6. this again is a community issue, though one that a tool doesn't help much to solve. Even more so than OSS, documentation efforts need to be inclusive. The mindset of the upper echelon of contributors needs to be: I want you to help everybody understand X and I am willing to go out of my way to make it happen. Without such community focus, documentation falls to becoming a chore for developers (and then suffers).
Docbook may not be the best solution, but it is certainly a better path than a wiki or some kind of q&a site like stackoverflow (this was actually suggested for some internal company documentation we need on a project; the thought was that we could use sharepoint). I suspect that some sort of version controlled text based format (as opposed to db-based format) is the way to go. hammett wrote: > In other words you want the best of both worlds. So far I havent found > such thing.. > > Might consider giving this drupal a try... > > On Fri, Oct 31, 2008 at 11:24 AM, Bill Barry <[EMAIL PROTECTED]> wrote: > >> I really don't care what the format we use is, just the following: >> >> 1. information is easy to find >> 2. information follows a sensible order (related things feel related, >> you aren't pushed to read something you don't need, you are pushed to >> read the things you do need to know first) >> 3. it is easy to contribute to >> 4. contributions are easy to review before inclusion >> 5. contributions are encouraged >> 6. contributors do not require the skills of a magazine editor (eg the >> documentation leader(s) could put out a request for info on a feature >> and a potential contributor like myself can give the raw facts without >> worrying about trying to make it easy to grok or concern that it will be >> ignored [btw, I am a bad example here because I'd probably fit more in >> at the editorial side than the fact giving side]). >> >> Am I missing anything? >> >> hammett wrote: >> >>> Some background for what's worth: >>> >>> - In the previous wiki style things were just too disconnected. Works >>> fine for wikipedia but not for something that might need to have a >>> reading order >>> - There was an attempt to keep each article on the new format very >>> short. This is pure usability. If people see a long scroll they feel >>> it's gonna take too much time to read and leave. This is especially >>> true for the getting started sections >>> - The format and organization was inspired by apache httpd documentation >>> - Keeping documentation for older versions was also inspired by the >>> apache httpd documentation and a book suggested this approach as well. >>> I think the book was "Producing Open Source Software" >>> - I sincerely dislike the docbook style, but I'm willing to give it a >>> try. Never really liked the way NHibernate and Spring are documented. >>> - The anakia style is also an attempt to keep formatting/layout >>> separated from the docs. I think that was successful, but it does make >>> contribution more difficult. >>> >>> >>> >>> >> > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Castle Project Development List" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/castle-project-devel?hl=en -~----------~----~----~----~------~----~------~--~---
