incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <>
Subject How documentation != code, and how to "do" policy (was: Re: Publishing api docs for Subversion)
Date Sat, 05 Dec 2009 10:45:28 GMT
Hey hey,

I wasn't going to say anything but since this is dragging on...

On Sat, Dec 5, 2009 at 1:08 AM, Doug Cutting <> wrote:
> Would we permit someone to mirror other files from trunk on the website?

Yes, definitely. Most projects publish their websites by pushing files
into SVN. Many projects automate this - commit an xml file, its turned
into html and published online. That is in fact the encouraged
process, though we do allow other mechanisms (like a plugin which
takes confluence content and pushes that out automatically).

>  What's special about documentation?

Less legal risk, less risk that anyone puts a bug in docs that crashes
a users computer or corrupts their data or takes down the internet,
generally not subject to patent concern, less desire for the general
public to fork and redistribute, and much more. Like, barriers to
working on it have to be as low as possible or no-one will do it,
people inclined to work on docs are often less technical, etc etc.

Perhaps it helps to flip the question around: what is special about
(source) code? And the answer is: lots :)

> its changes are subject to vetos, etc.

Not on most of the projects I work on! Most projects use lazy
consensus for documentation. I don't think I have *ever* seen someone
veto a documentation patch.

> It's otherwise treated just like code.

Well, in some ways (that you pointed out) docs are treated a lot like
code, and in many other ways they aren't.

>> Publication & release are two different things - thats the point.
> I don't see that yet.  Can you tell me more about the difference?  I use
> "publish", "distribute" and "release" more or less synonymously when
> referring to project content.

I'd say we don't really have precise definitions that will provide you
with a model explaining exactly what is and isn't ok in the general
case, and I think it won't help to look for it either. Instead,
judgement should be applied to the specific case.

> Subversion contains only working drafts.

And stable branches and release tags and documentation and websites
and quickbooks and contact info and meeting minutes and ... We use
subversion for nearly everything that needs to be auditable and be
backed up and be collaboratively edited. We don't always particularly
care about the versioning bit :)

But, for the sake of illustration, let's do a mental exercise.

The ASF does creation and distribution of software to the general
public. When we say "software" we mostly mean "source code (and some
binaries for convenience)". Pretty much everything around here is
structured to support this creation and distribution of software.

There's a variety of supporting things, like websites, incubators, an
org structure, various committees, conferences, etc. All of it
supports creation and distribution of our software.

What constitutes the software that a project releases to the public
depends on that project.

Subversion is one project, it has a website and it creates software
which it distributes. Subversion releases a single tarball of (mostly
C) source code with some build scripts and whatnot. Running the build
produces an apache module, a server program, a client program and some
utilities. Subversion's users then install this software on their
system and use it. Most subversion users probably get a pre-built
binary from a third party.

The subversion project provides a manual for how to install and use
svn on its website, but I suspect most users will actually use the svn

There is a relatively small side activity for subversion which
involves using its libraries and APIs to build custom client software
that interacts with a subversion server (or perhaps even extend the
server though I think very few people do that). For this activity, you
need the API docs we're talking about here. Of course, the subversion
developers themselves need those API docs too.

It's a fair assumption that the expert developer people using these
API docs know *quite a lot* about subversion already, including about
its versioning and compatibility policies, how to download releases
and code out of svn, etc etc. It's also a fair assumption that the
most important API to develop against is in fact the SVN trunk API.

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.

Now, the point of this long story: subversion as a community has
thought about all this and are evidently doing a pretty good job at
keeping users and wider developer community (well perhaps not the java
dev community who are afraid of native code :-D ) happy.

Within all this context, one of the subversion developers (or this I
assume) asked a tech-focused question on where they should put their
API docs and how to do so automatically. Good that he asked, ideally
he should receive a quick answer that allows him to get on with
creating software and distributing it to the public - incubator is
here to enable that.

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.

Perhaps the worst possible response is making an assertion about
policy saying in effect "you're not allowed to do what you're trying
to do", followed by a long discussion thread about why that assertion
is correct, based on an interpretation of generic ASF policy as it
applies or (c|sh)ould apply to websites.

Please don't make these generic/sweeping assertions when someone from
an incubating project asks a specific-to-them specific question. The
effect is to stall progress which is unhealthy for that project's

If you have an idea about what the policy is, check your idea against
the extensive docs on and If
your idea is in there, point people at the documented policy. If the
reverse of what you thought is in there, you can answer with what you
just learned. If the answer is not in there, then maybe it makes sense
to start a discussion thread (where I sort-of expect people that talk
about policy volunteer to update the website docs with the outcome of
the discussion), but don't bother the incubating project with that
stuff, and in the meantime its a good idea to err on the side of

If you must make a generic assertion that's not obviously backed by
existing policy documentation, make sure to add "I think that the
normal approach is" or "I believe that the best thing to do is" rather
than state SHOULD or MUST. Focus on helping the incubating project
achieve their goal.

If you make such a generic assertion anyway, and several of your peers
around here goes "excuse me, I disagree", then the reflex behavior
should be something like "oh, go ahead then". There can still be a
discussion about what the policy should be, but _please_ _please_ just
let the incubating project go and get stuff done, start a new thread.

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".

You know, often times I think the best engineers can be the worst
policy-makers: as engineers we tend to build models and abstractions
and look for the rules and the invariants and then express those as
clearly as possible. But abstractions are leaky, invariants are
variable, and clear rules can look pretty aggressive to the casual
human. We have to let go of all that rigid thinking in order to make a
reasonable policy that can be used by humans.

I always look to creative commons for great examples of this. I.e. compare


I think nearly everyone can agree on which is "friendlier" :)



To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message