a lot of activity on this topic again ;) just to put my points with your outline:
1. anakia or docbook are great, sadly I don't know enough of them to ensure that the current doc site can be outputed with docbook or if we can work on a anakia to docboook merge module that will allow to declare anakia files to be integrated at some point in a docbook TOC. The problem with manual transformation is that it's unmanageable to perform this for the whole documentation, as well it's unmanageable to abandon the current doc site which is great. The perfect solution would be 100% automated docbook meta description to merge anakia files 2. maybe a dedicated docs directory should be along the project top directory, I'm sure most of times, source checkout only occurs on trunk and not the root (which contains the site directory), that would ease the way for better documentation (commiters would only apply a patch if described features came along in the docs) 3. that's ambitious, I find separate builds of the docs (as it exists now) is good enough before committing to such feature 4. agree 5. api.castleproject.org seems to be well indexed, is it refreshed by the build server? 6. agree, the docs rarely come on top when searching the web 7. there should be a poll on the forum (I mean accessible on the forum), maybe some people are attached to it (I don't use it anymore) because it has some features google groups don't have (minor, eye candy for most) On Oct 31, 8:38 pm, "Ken Egozi" <[EMAIL PROTECTED]> wrote: > 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/bloghttp://www.musicglue.comhttp://www.castleproject.orghttp://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 -~----------~----~----~----~------~----~------~--~---
