From: Chad Perrin <code@...>
Date: 2011-08-03T07:32:43+09:00
Subject: Re: Documentation Improvement Proposal

--PNTmBPCT7hxwcZjr
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Wed, Aug 03, 2011 at 05:22:32AM +0900, Adam Prescott wrote:
> On Tue, Aug 2, 2011 at 8:46 PM, Steve Klabnik <steve@steveklabnik.com>wro=
te:
>=20
> > Documentation should be crafted. Tons of people throwing random
> > code samples at the bottom of the page is not helpful. See Eric's
> > response: "User contributions should be aggressively curated to fold
> > documentation improvements back in to the source material and remove
> > bug reports and "how do I use this?" type questions." I can't repeat
> > this enough.
> >
>=20
> Agreed. I think it's worth sacrificing the "total" (bearing the bureaucra=
cy
> of Wikipedia in mind) freedom to edit, in exchange for a greater quality =
in
> the material, which will more than likely come about from someone curating
> aggressively.

I'd like to see things broken up into four parts, actually, to take a
somewhat collaborative approach.

0. issue tracker page, where people ask for stuff and make notes about
things that need to be done

1. discussion page for each page of documentation

2. development page for each page of documentation, handled a bit like a
version control system -- drawing on stuff in the discussion page

3. "official" page, which is a curated version of what arises in the
development page

Make *all* of them publicly accessible, with varying levels of editing
access control (where only an "official" team has editing access to the
"official" page, of course, all the way down to general, free public
access to report things to the issue tracker).

It's possible the issue tracker and discussion could somehow be rolled
together into one thing.

--=20
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

--PNTmBPCT7hxwcZjr
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.14 (FreeBSD)

iEYEARECAAYFAk44dv4ACgkQ9mn/Pj01uKVqYQCgoExMebQhCYCVwTlygGVgxtLZ
II8An14GJBtjbtwaBpjucZ1I94VWI+8y
=y94x
-----END PGP SIGNATURE-----

--PNTmBPCT7hxwcZjr--