I just had a short discussion on the docs with Symon this morning, and I've reflected on that all day, just to be back home ans see this thread :)
just a sad anecdote: in the Monorail poll I'm conducting I'm asking people for where they get help and info from. the options are "blogs", "forums", "mailing list", and an open "other" box. I left "docs on Castle site" out for a reason, wanting to see who will come it an write it down in other. it took 55 people to get to the only one that has stated Castle site in his poll submission. all others look in the lists and blogs. my many pences: 1. on format: I most certainly agree that docs should not be a wiki. I liked the anakia way very much, and I consider the docbook way the same - keeping the data in the xml files and use some voodoo and xsl to transform into html/chm/(pdf?) the critisism on the resulted html format is in place, but surely the build process can be twicked to create the desired format, preferrably following the current documentation in the site, which does offer a more structured and begginer's pleasing look. 2. on location: the doc sources should reside within the same repo as the projects, and should be considered a part of the projects. meaning: a patch that changes (or enhances) documented behaviour should contain an update to the docs. if it has implications for the 'getting started' sample projects, they has to be included within that patch. 3. on archive: the main documentaion on the site, for each project (see 4.) , should present the latest release. previous releases should be linked to. kind of what MSDN offer. 4. on documentation split: the documentation per project should be split, just like it is for the projects themselves. 5. api documentation: that is generated from the comments in the code files, should be visible somewhere where google can index it, but that's about it. I think it's way less important than the actual docs. 6. on linking: the only way we could make the docs visible would be to get igh profiled bloggers/forums/knowledge sites link to the docs. As some of us know some of these personally it should be acheivable 7. on the forums: they should be dropped altogether. the mailing list serves the purpose better, is easier to maintain and monitor, and is even more google-able. On Fri, Oct 31, 2008 at 9:18 PM, Bill Barry <[EMAIL PROTECTED]> wrote: > 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]> <[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. > > > > > > > > > > -- Ken Egozi. http://www.kenegozi.com/blog http://www.musicglue.com http://www.castleproject.org http://www.gotfriends.co.il --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
