incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Doug Cutting <cutt...@apache.org>
Subject Re: How documentation != code, and how to "do" policy (was: Re: Publishing api docs for Subversion)
Date Mon, 07 Dec 2009 19:03:36 GMT
Leo Simons wrote:
> So, subversion publishes their trunk API docs nightly, for the
> convenience of their own developers and the surrounding tool developer
> community. All those people mostly want trunk API docs, and they want
> them mostly so they don't have to run doxygen themselves. There's
> really no need to protect the normal users of the subversion website
> from "bad" API docs, they won't be using those docs at all.

It's fine to make nightly builds available, including of documentation. 
  All I'm suggesting is that, just as nightly builds should not be 
linked to from the general download page, nightly documentation should 
not be linked to from the general documentation page.  Both, like links 
to ViewVC, should only be linked to from developer-specific pages.

> The best response in this case is probably to look for a similar
> project around the ASF that has already figured out a similar process
> and see if things are compatible. Like, httpd or apr. Ah, they do the
> same. Cool, done.

Just because HTTPD or any other project does something does not always 
mean it's best practice.  It often does, but, in this case, I think 
adding "dev" to a link in the sidebar is a poor substitute for moving 
this link to http://httpd.apache.org/dev/.

> If you have an idea about what the policy is, check your idea against
> the extensive docs on www.apache.org/dev/ and incubator.apache.org. If
> your idea is in there, point people at the documented policy.

I believe I cited this earlier in the thread:

http://www.apache.org/dev/release.html#what

"Do not include any links on the project website that might encourage 
non-developers to download and use nightly builds, snapshots, release 
candidates, or any other similar package."

This is motivated by legal reasons.  Copyright and license issues are 
possible for documentation as well as code, so I see no reason to make 
an exception for nightly documentation builds.

> Always remember the incubator is not here to invent policy and apply
> it to incubating projects. The incubator is here to help incubating
> projects navigate the ASF so they can create and distribute software
> "ASF style".

I'm not inventing policy.  I'm describing the way every project I'm 
involved with operates and interpreting the rules posted at 
http://www.apache.org/dev/.

Doug

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org


Mime
View raw message