In article <[EMAIL PROTECTED]>, "James A. Treacy" <[EMAIL PROTECTED]> writes: > You have brought up the two items I was interested in: structure and > document readiness. As far as structure is concerned, it would be > helpful to those writing documentation if the location of documents > is consistent between the different areas that use them, ie. the > archive, debian web pages and /usr/doc/ on machines at home. With > that in mind the location of Debian documentation was following the > structure of /doc in the archive (there seems to have been some > divergence over time though).
Good point. Here we start to see the start of the debian developer's documentation guideline document, I guess. Suppose that the <package> is the kicker, so we say: * install the package and get /usr/doc/<package>/<package>.html (wouldn't /usr/doc/<package>/index.html be better?) * also find it at http://www.debian.org/<package>/<package>.html (wouldn't http://www.debian.org/<package>/index.html be better?) * find devel copy at <DDP-ROOT>/<package>/<package.html (ditto) > I would much prefer it if the doc people told us how to organize the > doc/ directory on the web site. Links from sections that need to > reference them can do so by pointing to the location under doc/ > . Also, there is at least one link from a Debian doc into another > one. That link is currently broken. Having a known structure to the > doc/ directory should alleviate that kind of problem. What do you think abou the above? Seems simple and transparent and all that. I like doc/<package>/index.html, and the DDP install system can be made to do this automatically pretty easily (not quite yet). > As far as document readiness goes, isn't this one of the uses of > branches in CVS? Development branches are split off and when a new > release is desired, you simply merge branches. Those only interested > in the stable branches can simply follow those. Yes... I guess I"m lazy. I guess I shoudl branch when I start a little unstable branch, and then merge it back into the main branch for a "release version" ? Never really tried it... >> The final issue is that if we're going to do this, we might as well >> propogate it into http://www.debian.org/devel/ as well, since many >> manuals can go there also. > As mentioned above, this is unnecessary. We can just link the > location under the doc/ directory. Yes, good idea, more consistent; see above! -- .....Adam Di [EMAIL PROTECTED]<URL:http://www.onShore.com/>
