[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

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

From: C. Michael Pilato <cmpilato_at_collab.net>
Date: Wed, 13 Jan 2010 16:16:26 -0500

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.

* 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.

-- 
C. Michael Pilato <cmpilato_at_collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand

Received on 2010-01-13 22:17:06 CET

This is an archived mail posted to the Subversion Dev mailing list.