> On 7/27/07, Noah Kantrowitz <[EMAIL PROTECTED]> wrote: > > I want to propose (well voice a proposal from Alec) that we move the > > official documentation in to the repo. There is a growing problem
I really can't take credit for any innovation here, I'm just proposing we emulate what Chris did for Genshi and Babel: http://genshi.edgewall.org/#Documentation http://babel.edgewall.org/#Documentation Canonical documentation is stored with the source, but trivially exposed in the Wiki. Documentation for the different versions of Trac are achieved by simply including from the appropriate part of the repository. Of course these projects don't (yet ;)) have the same number of users as Trac, but it seems like a reasonable model to me regardless. On 7/28/07, Emmanuel Blot <[EMAIL PROTECTED]> wrote: > > So if I understand it right, it means that we need people/time to > review all the documentation and a strict peer reviewing of the > documentation to produce official docs ? The initial import of the docs would be no more work than we currently do when moving the base docs into trunk before a release (ignoring any reorganisation and cleanup we might like to do as well, of course). Ongoing I see it being less work. At the moment we spend a not insignificant amount of time fixing user changes to the Wiki. With the proposed plan, the Wiki would be for users to "self help", with the repository for official Trac documentation. > Do we have the human resources to move to this model? I have strong > doubts about this point. In what way? > We need a clearer documentation model, but moving it to the repository > seems a bit "too strong" from my perspective. > Having two (or more) source of information (official docs, wiki pages > on t.e.o.) is also quite confusing for the end user. I don't believe this is true. > OTOH, I think the first thing to do about the docs is to "branch" it: > one area for Trac 0.10, another area for Trac 0.11 - which means > duplication of info - but we really need to create two areas rather > that to add those "since 0.11" stuff. 0.11 is really different than > 0.10, and I agree: t.e.o. is getting more and more confusing each day. > > Having docs on the repository could improve the quality of the > documentation, but we might miss hands to update the repository on a > regular basis. I think this is a matter of training ourselves: "When developer adds/changes a feature, update documentation as well. Commit.". This could in fact make documentation better by reducing the cognitive overhead of having to switch from "coding mode" to "documentation mode". > Anyway, whatever the model we choose, we first need to define how we > organize the files/pages first. I can't build a mental picture of > t.e.o. documentation right now. There are several pages to store > similar information (such as TracFaq, trouble shooting guide and the > like) I'd propose we just use the existing documentation layout in subversion to start with, and reorganise as we go: 1. Convert current "official" docs into [[Include(/path/)]] (preferably with different "trees" for each Trac version). 2. Create a documentation landing page "TracDocumentation" with links to the documentation for different versions. Maybe create links to some user "self help" pages as well. Maybe the FAQ should be self help. For point 1. it might be useful to have a macro installed on TEO to expose all this documentation with one call: [[TracDocumentation(/trunk/trac/wiki/default-pages)]] Or something. There's another potential opportunity here too: removing the user visible wart of having all the documentation in their Wiki and timeline. A request handler could be written to serve Trac documentation instead. Just a thought. -- Evolution: Taking care of those too stupid to take care of themselves. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Trac Development" 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/trac-dev?hl=en -~----------~----~----~----~------~----~------~--~---
