launchpad-dev team mailing list archive

[Gavin Panella <gavin.panella@xxxxxxxxxxxxx>]

On 5 October 2011 17:13, Julian Edwards <julian.edwards@xxxxxxxxxxxxx> wrote:
[...]
> I'm pretty sure you guys are more opinionated than this. C'mon, let
> us have it :)

Right!

- Moin sucks as a wiki.

  - The syntax is /okay/, but its parser seems broken in some
    situations. Indented blocks, lists and wrapped source text seem to
    bother it.

  - Search. Need I say more.

- rST and Markdown seem to have the market in portable wiki-like
  structured markup. Can use rST in Moin, but support is incomplete
  (categories and macros don't work for example).

- I would love to put docs in Launchpad tree, using the Sphinx stuff
  that jml set up, but landing to LP is a heavyweight process and I
  suspect will always be a bit too heavyweight for writing docs.

- Doctest is often waved around as the solution to documentation rot,
  but I think it actually makes for terrible documentation as well as
  terrible tests. Just go and read some of the forced narratives on
  PyPI arising from the use of doctest. I don't want to read doctest
  in *any* form.

- I think we have to accept that documentation will rot to some
  degree. I think it's the responsibility of *both* those who change
  code (leaving the docs behind) *and* those who discover that the
  documentation is out of date to bring it up to date.

- Wikkid seems nice :) Update docs via the web or via a
  branch. Perfick.