On 5 October 2011 10:34, Julian Edwards <julian.edwa...@canonical.com> 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 _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : launchpad-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
