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