Hyrum K. Wright wrote:
>> I propose that docs like the merge-tracking design stuffs and hacking
>> and other developer-focused materials continue to live under /trunk, be
>> maintained alongside the code those things are aimed at, etc. But of
>> course, on our public website's "Developer Resources" page (or
>> whatever), we link directly to trunk/notes/dev/hacking/index.html via
>> its Subversion resource URL and let mod_dav_svn serve it up. In other
>> words, documents of common import to developers can still be *linked
>> to* from our website, but they needn't rest outside our source tree.
>
> While I agree that it's technically possible to put html content anywhere
> in the repo (so long as mod_dav_svn serves it up with the proper MIME
> type), I don't think we need to. The entire point of putting stuff close
> to where it's used it to make it predictable to find. But physical
> locality is not a prerequisite for predictability. So long as folks know
> where in site/ to go for the documentation, it doesn't matter if it's in
> notes/dev/hacking or site/dev/hacking.
...except that "site" lives outside our trunk/branch structure, away from
the code.
I should pause right here and say that, in retrospect, "hacking" might be a
poor example of the kind of document I was primarily looking to move out of
"site". It's not so much a technical document about Subversion as it is a
community how-to, and I'm okay with that kind of thing living under "site".
So keep that in mind as you read the rest of my response, please.
> Putting content in multiple locations seem brittle from a maintenance
> perspective.
We already have stuff in multiple locations. We have trunk/www and we have
trunk/notes. We made the decision some time ago to divide our information
not by its target reader but by -- of all things -- the file format we
happened to use to author the thing. That's nonsensical, and its precisely
the kind of insanity I'd like to put a stop to.
> We're using SSI and other Apache magic to keep stuff
> maintainable. Will any of that break if we try to serve up content
> through mod_dav_svn?
Yes, all of it will break. But it also breaks when you take a link to our C
API. Or to our Java docs. Or to the ASF website, or our mailing list
archive browser, or... The SSI stuff is only there to facilitate
navigation around the body of information that we choose to consider "our
project website".
> What about when somebody wants to add a new page;
> is that process straightforward?
Yes. If they want to add a user- or community-focused document (the kind of
thing that lives on our "website") they add it under "site". If they're
adding a feature design document (regardless of whether its composed in
ASCII, Word, HTML, or otherwise), it goes to "trunk/notes".
> Will a domain-specific search of s.a.o
> also pull up pages in notes/ ?
No. But it doesn't do so today either, so what's the point?
> I'm not opposed to trying out a different, but the voice in the back of
> my head says we should keep all the html content in one predictable
> place.
See above about grouping information merely by file format.
I'm not trying to be argumentative for the sake of being argumentative. I'm
speaking from (too much) experience of trying and failing to quickly find
information in its current arrangement. Maybe I'm alone in this, but when I
think, "Where's the merge tracking design doc?" I don't want to have to
remember "Oh yeah, that's written in HTML so it probably lives in /site". I
want to think, "That's a technical doc, so it lives in /trunk/notes with all
the rest of the technical docs."
Now, there's another option available to us here that's not been discussed,
and that's to convert the whole of "trunk/notes" to HTML (if only just a
ginormous <pre>...</pre> block) and move the lot of it to "site". I'm not
terribly fond of the idea because (again) it moves our technical notes away
from the code.
--
C. Michael Pilato <cmpilato_at_collab.net>
CollabNet <> www.collab.net <> Distributed Development On Demand
Received on 2010-01-14 05:23:27 CET