Re: svn commit: r898937 - /subversion/site/site-map.txt

On Jan 13, 2010, at 3:16 PM, C. Michael Pilato wrote:

> Hyrum K. Wright wrote:
>> In general, I agree with this idea. It's kinda painful to have to go
>> search notes/, and then the website when looking for various docs.
>> But....
>>
>> Staring at plain text files can be painful (especially something as long
>> as HACKING). Links within and between documents is useful, especially in
>> technical documentation. Being able to link to a specific part of a
>> document, such as the patch or log message section is invaluable. And it
>> helps to be able to use non-ascii illustrations, variable-wdith fonts,
>> font-size differences, etc.
>>
>> For all of these reasons, I'd like to advocate that we keep documentation
>> in html, perhaps in a dedicated dev/ part of the website. And yes, this
>> may mean that we move notes/ to site/dev/ .
>
> I think you've brought a whole bunch of assumptions into this that needn't
> be brought.

Well, I do have a penchant for collecting assumptions. Here's blue one ... and a green one ... and a purple striped one (it matches the bikeshed out back).

> * Who has said that trunk/notes must be plaintext files only? Not I. Rich
> text is valuable, and we'd be well-served to make even more use of it here
> in 2010.
>
> * Who says you have to search through trunk/notes and the website to find
> something?
>
> 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.

Putting content in multiple locations seem brittle from a maintenance perspective. 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? What about when somebody wants to add a new page; is that process straightforward? Will a domain-specific search of s.a.o also pull up pages in notes/ ?

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.

-Hyrum ( oh look! I just found a fuxia one ...)
Received on 2010-01-13 22:53:20 CET