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