launchpad-dev team mailing list archive

[Matthew Revell <matthew.revell@xxxxxxxxxxxxx>]

On 5 October 2011 10:34, Julian Edwards <julian.edwards@xxxxxxxxxxxxx> wrote:

> I think we are all pulling in different directions and nobody is steering the
> rudderless documentation ship.
>
> There are now three places to maintain documentation: the dev wiki, RTD
> (Sphnix) and doctests.  I'd like to start a rational discussion on how we
> should be managing this sort of thing because quite frankly it's getting
> annoying not knowing where to look, even if I already know something is on the
> wiki.
>
> Stub's "wikis are where documentation goes to die" is a bit of an emotional
> comment but reminds us that documentation is able to become out of date very,
> very quickly unless it's maintained. Doctests, while able to help a little
> here, are not a panacea.  So, I differ from him in that I believe this applies
> no matter where documentation lives.
>
> I do like the general idea of keeping documentation in our tree and generating
> HTML from it.  It's partly why I started the /LongPoll wiki pages in rst
> format so that we can drop the same raw text anywhere.  Doing this seems to
> have several advantages:
>
>  * it's more easily searchable
>  * it's available offline
>  * it's easier to update the documentation along with the code

Also, you need commit rights and have to go through a code review to
make a change, which is a good thing.

Open wikis are pretty useful when you have a large, knowledgeable and
tireless group of people to maintain them. In this case, we need
accuracy more than we need total openness. If we had that large group
then "many eyes make [wiki errors] shallow" might apply and help us to
weed out errors and generally improve what we have.

However, we don't have a large group of people willing/able to do
that. So, instead we're expecting a small group of people to stop what
they're doing and verify changes to the dev wiki. Those interrupts are
bad for productivity and mean that the checking of changes to our dev
docs becomes dependent on whether one of the notified people has the
time/inclination to verify it.

Accuracy matters in our dev docs. Quality also matters, if we're to
attract and retain people to our development community.

The docs in the tree, whether doctests or Sphinx stuff, have a review
process that we know how to run and that works well. So, I favour
seeing our official developer documentation in the tree for that
reason, as well as those that you give.

The dev wiki has its place:

 * it's a good way to collaboratively develop documentation before it
goes in the tree
 * time-sensitive information, such as a release calendar, doesn't
really belong in the tree
 * it's great for all those other things we'll never put in the tree,
such as less formal how-tos and LEPs.

> Perhaps the dev wiki should only contain information that is more likely to
> remain static, such as "getting the code", "debugging tips" etc.

Interestingly, I think the opposite: the dev wiki should be a mix of
documentation nursery and place for documents (not just documentation)
that don't belong in the tree. The dev wiki is a place where we can
say, "Hey, this might be useful but we can't necessarily vouch for
it".

The docs in the tree, though, have our stamp on them.

Now, as for whether we favour Sphinx docs or doctests, I'm a little
less clear on. I prefer the Sphinx stuff because anyone can access
them via rtfd. However, my experience with doctests is pretty limited.

As for maintenance, I think this is clearly something everyone in the
LP team should consider part of what they do, but I'd like to think
the Product team might have time to help shepherd the docs. I can't be
more specific than that until we've hired the new Usability and Comms
person and I have a better idea of how their time will be spent.

-- 
Matthew Revell
Launchpad Product Manager
Canonical

https://launchpad.net/~matthew.revell