On Jan 13, 2010, at 10:22 PM, C. Michael Pilato wrote:
> 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".
I think it's generally understood that generated documentation doesn't necessarily conform to the parent site's guidelines. In fact, one of the benefits of generated docs, such as Javadoc, is that it's uniform across various sites; *everybody* knows what a Javadoc is.
>> 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?
It's an added value that we're foregoing. Opportunity cost and all that.
>> 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.
At the end of the day, I have faith in the abilities of folks who know more about web site design and organization than I do. I've already admitted my lack of competency, I just wanted to make sure my thoughts and concerns were taken into consideration. Things are still fungible, so let's go with what we've got planned in site/site-map.txt, and see where we go from there.
-Hyrum
Received on 2010-01-14 17:14:27 CET