subversion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "C. Michael Pilato" <cmpil...@collab.net>
Subject Re: svn commit: r898937 - /subversion/site/site-map.txt
Date Wed, 13 Jan 2010 21:16:26 GMT
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@collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand


Mime
View raw message