[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: doc directory of the web pages



In article <[🔎] 19981125115159.X430@debian.org>, "James A. Treacy" <treacy@debian.org> 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 Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>


Reply to: