You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@incubator.apache.org by Doug Cutting <cu...@apache.org> on 2009/12/07 20:03:36 UTC
Re: How documentation != code, and how to "do" policy (was: Re: Publishing
api docs for Subversion)
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
Re: How documentation != code, and how to "do" policy (was: Re: Publishing
api docs for Subversion)
Posted by Doug Cutting <cu...@apache.org>.
Doug Cutting wrote:
> > In the absence of specific policy then *objections* are out of order
> I have not objected to anything.
Forgive me. I did in fact use the verb "object" in a prior message:
> * Do you object to publishing non-released documentation on the
> project Web pages?
>
> I object to posting these outside of a clearly-marked developer portion of the project's web site.
I didn't mean this as a veto or formal objection. I was rather using a
parallel construction to better make clear my view. I meant this in the
informal sense that I would argue this is not the best approach.
Sorry for any misunderstanding.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: How documentation != code, and how to "do" policy (was: Re: Publishing
api docs for Subversion)
Posted by Doug Cutting <cu...@apache.org>.
Niall Pemberton wrote:
> You're taking a
> policy that applies to release artifacts and stretching it to
> something it wasn't intended to cover.
Applying the rules for releases to significant subsets of releases
doesn't seem like much of a stretch to me. Subsets are subject to the
same copyright and license concerns, the motivations for the rules.
> 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.
What? I can't state what I believe to be a best practice?
I have not objected to anything. Someone asked about posting
pre-release documentation, and I remarked that, like pre-release code,
they should keep it distant from released documentation, ideally only
linked from the developer portion of their site. Is that really a bad idea?
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: How documentation != code, and how to "do" policy (was: Re:
Publishing api docs for Subversion)
Posted by Niall Pemberton <ni...@gmail.com>.
On Mon, Dec 7, 2009 at 7:03 PM, Doug Cutting <cu...@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
Re: How documentation != code, and how to "do" policy (was: Re:
Publishing api docs for Subversion)
Posted by Leo Simons <ma...@leosimons.com>.
On Tue, Dec 8, 2009 at 5:16 AM, Niclas Hedhman <ni...@hedhman.org> wrote:
> this is also the case for Nightly Builds, accessible by the
> public; Legally they are "publishing to the public" (i.e. opposite of
> 'for private use') and bound by licenses and agreements.
> And finally, from Copyright law perspective, you are right that code
> and text is effectively the same thing, but that code has a common
> tendency to be depending on other work, introducing licensing into the
> legal mix. I think it was Leo who also pointed out that Trademarks is
> an additional legal aspect of it.
I have no idea what "it" you mean exactly, but I'm pretty sure I said
nothing about nightly builds and I said nothing about trademarks.
Here's some of what was said just a few e-mails back:
> Doug:
>> What's special about documentation?
>
Leo:
> (...) Less legal risk (...), generally not subject to patent concern
which I probably should not have said since I didn't back it up with a
reasonable reference. Sorry about that.
cheers,
Leo
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: How documentation != code, and how to "do" policy (was: Re: Publishing api docs for Subversion)
Posted by Joe Schaefer <jo...@yahoo.com>.
----- Original Message ----
> From: Niclas Hedhman <ni...@hedhman.org>
> To: general@incubator.apache.org
> Sent: Tue, December 8, 2009 1:03:51 AM
> Subject: Re: How documentation != code, and how to "do" policy (was: Re: Publishing api docs for Subversion)
>
> On Tue, Dec 8, 2009 at 1:37 PM, Joe Schaefer wrote:
> > There's also a world of difference between worldwide distribution
> > and distribution to a self-selected subgroup.
>
> You are right that it is a big "IMHO" of everything here, but
> "self-selected subgroup" is not a legal term in copyrighted material
> either. So, no clue of who has no clue ;-)
> Either it is available to the public or it is not. And as I mentioned,
> in EU people at your work place are "public" and not "private", vs
> friends are "private". Now that definition probably differs in
> different jurisdictions, so if you have credential requirements then
> you are in a different, more 'at work'-like situation. The fact that
> "anyone can download" makes it "public" no matter how you look at it.
>
You keep bringing up this point as if it were somehow relevant to the
discussion. Noone is disputing that these are public works, what is
being disputed is the nature of the work and the scope of the distribution.
> "Liability considerations", not sure what you are trying to hint, or
> whether you just try to toss me off the track... It is easy to be
> vague and sound educated.
Well do a little looking into how the RIA is prosecuting copyright offenses
and you'll see that "damages" are assessed according to the number of
offenses. That is a liability consideration- courts will laugh at the RIA
for attempting to prosecute file-sharers with relatively few known distributions
of copyrighted material. And that distinction is the main point the ASF is
trying to establish with dev-only distributions vs. world-wide distributions
(aka releases), ideally that an aggrieved copyright holder's redress would be
limited to pulling the offending material in the case of a dev-only distribution.
Is this a court-tested principle? Of course not, but that doesn't make the concept
or its pursuit invalid.
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: How documentation != code, and how to "do" policy (was: Re:
Publishing api docs for Subversion)
Posted by Niclas Hedhman <ni...@hedhman.org>.
On Tue, Dec 8, 2009 at 1:37 PM, Joe Schaefer <jo...@yahoo.com> wrote:
> There's also a world of difference between worldwide distribution
> and distribution to a self-selected subgroup.
You are right that it is a big "IMHO" of everything here, but
"self-selected subgroup" is not a legal term in copyrighted material
either. So, no clue of who has no clue ;-)
Either it is available to the public or it is not. And as I mentioned,
in EU people at your work place are "public" and not "private", vs
friends are "private". Now that definition probably differs in
different jurisdictions, so if you have credential requirements then
you are in a different, more 'at work'-like situation. The fact that
"anyone can download" makes it "public" no matter how you look at it.
"Liability considerations", not sure what you are trying to hint, or
whether you just try to toss me off the track... It is easy to be
vague and sound educated.
Cheers
--
Niclas Hedhman, Software Developer
http://www.qi4j.org - New Energy for Java
I live here; http://tinyurl.com/2qq9er
I work here; http://tinyurl.com/2ymelc
I relax here; http://tinyurl.com/2cgsug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: How documentation != code, and how to "do" policy (was: Re: Publishing api docs for Subversion)
Posted by Joe Schaefer <jo...@yahoo.com>.
There's also a world of difference between worldwide distribution
and distribution to a self-selected subgroup. Niclas has no clue
what he's talking about when liability considerations are factored in,
and as this is not a list where legal council for the ASF makes itself
available I suggest his words be considered with a big fat IMHO around
them.
----- Original Message ----
> From: William A. Rowe Jr. <wr...@rowe-clan.net>
> To: general@incubator.apache.org
> Sent: Tue, December 8, 2009 12:29:42 AM
> Subject: Re: How documentation != code, and how to "do" policy (was: Re: Publishing api docs for Subversion)
>
> Niclas Hedhman wrote:
> >
> > So, any policy in the area is not really bound in the legal space, and
> > more in the 'representation of ASF'-space.
>
> No, there is a legal distinction between work-product (the intermediate
> steps) and a publication. Posts like this might attempt to muddy the
> distinction, so it's our job to communicate to the general public which
> bucket is which, and where they can find them.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: How documentation != code, and how to "do" policy (was: Re:
Publishing api docs for Subversion)
Posted by Niclas Hedhman <ni...@hedhman.org>.
On Tue, Dec 8, 2009 at 1:29 PM, William A. Rowe Jr. <wr...@rowe-clan.net> wrote:
> Niclas Hedhman wrote:
>>
>> So, any policy in the area is not really bound in the legal space, and
>> more in the 'representation of ASF'-space.
>
> No, there is a legal distinction between work-product (the intermediate
> steps) and a publication. Posts like this might attempt to muddy the
> distinction, so it's our job to communicate to the general public which
> bucket is which, and where they can find them.
Uhhhh.... So this is a USA-specific concept?
>From my experience (Sweden, now under EU Law), there is two central
concepts (regarding "publish") of work under Copyright; a) Right to
Copy, b) "Making available to the public" vs "private use".
For instance; I have the right to copy a CD for private use, incl
giving it to a friend. I don't have the right to copy a CD and make it
available to the public, not even work colleagues.
Apache's dev section is not "private use" and therefor would fall
under "making available to the public".
Absurd Example; "I have obtained the right to make derivative work
(for instance paying money for it) of a famous song, with some strong
restrictions. The end result will be a freely downloadable work. So, I
create my "work-product" which is the original song, and have that
available to the public for download...." No way that there is room in
the law for that... Because then you could claim, "Oh, this full copy
of the book is 'work-product' since I will have an excerpt under 'fair
use' in my book, and the full book will not be part of the end
result."
Sorry, I don't buy it, that US law can be that flimsy. My guess is
that "work-product" is only applicable in closed environments (i.e.
not public), but I think you need to point me to the legislation in
question.
Cheers
--
Niclas Hedhman, Software Developer
http://www.qi4j.org - New Energy for Java
I live here; http://tinyurl.com/2qq9er
I work here; http://tinyurl.com/2ymelc
I relax here; http://tinyurl.com/2cgsug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: How documentation != code, and how to "do" policy (was: Re:
Publishing api docs for Subversion)
Posted by "William A. Rowe Jr." <wr...@rowe-clan.net>.
Niclas Hedhman wrote:
>
> So, any policy in the area is not really bound in the legal space, and
> more in the 'representation of ASF'-space.
No, there is a legal distinction between work-product (the intermediate
steps) and a publication. Posts like this might attempt to muddy the
distinction, so it's our job to communicate to the general public which
bucket is which, and where they can find them.
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: How documentation != code, and how to "do" policy (was: Re:
Publishing api docs for Subversion)
Posted by Niclas Hedhman <ni...@hedhman.org>.
On Tue, Dec 8, 2009 at 3:03 AM, Doug Cutting <cu...@apache.org> wrote:
> 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.
Well, depends on what you are talking about. From a legal perspective
there is no difference between "developer pages" and "public pages",
as long as they are both accessible without login. IMHO, I would claim
that this is also the case for Nightly Builds, accessible by the
public; Legally they are "publishing to the public" (i.e. opposite of
'for private use') and bound by licenses and agreements.
And finally, from Copyright law perspective, you are right that code
and text is effectively the same thing, but that code has a common
tendency to be depending on other work, introducing licensing into the
legal mix. I think it was Leo who also pointed out that Trademarks is
an additional legal aspect of it. Nevertheless, nightly builds is IMHO
from a legal perspective an act of "making available to the public"
regardless whether that is in the "developer section" or not.
So, any policy in the area is not really bound in the legal space, and
more in the 'representation of ASF'-space.
Cheers
--
Niclas Hedhman, Software Developer
http://www.qi4j.org - New Energy for Java
I live here; http://tinyurl.com/2qq9er
I work here; http://tinyurl.com/2ymelc
I relax here; http://tinyurl.com/2cgsug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org