subversion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Hyrum K. Wright" <>
Subject Re: svn commit: r898937 - /subversion/site/site-map.txt
Date Wed, 13 Jan 2010 21:52:41 GMT

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 ...)
View raw message