incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Niall Pemberton <niall.pember...@gmail.com>
Subject Re: How documentation != code, and how to "do" policy (was: Re: Publishing api docs for Subversion)
Date Mon, 07 Dec 2009 19:35:15 GMT
On Mon, Dec 7, 2009 at 7:03 PM, Doug Cutting <cutting@apache.org> wrote:
> 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/.

You're representing something as policy that is not. You're taking a
policy that applies to release artifacts and stretching it to
something it wasn't intended to cover. In the absence of specific
policy then *objections* are out of order since its up to the PMC of a
project to decide these things. We also have a responsibility here to
not make incubating projects cry and weep and wonder why they ever
wanted to join the ASF - which threads like this over where to put a
link on their site must surely do.

Niall

> Doug

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


Mime
View raw message