Documenting Features

[Ben Cotton]

On Tue, Jan 29, 2013 at 7:29 PM, pete <me at petetravis.com> wrote:

>         - Ensuring the content of the Feature is understandable by a
> hypothetical average user.
>         - Working up a basic guide to implementing the feature, if applicable

The primary purpose of the feature page, IMO, is communicating and
tracking the technical description of the feature. Making feature
pages understandable to the lay user is a job for the release
announcement and the tech journalists. A guide to implementing the
feature is a really good idea in theory, but I have a lot of concerns
about trying to make it happen. We have a hard time getting beat
writers already, and adding extra work probably won't help. We can't
even reliably ship the User Guide.

The rest of the proposal seems to hinge around changing from using
beats as the focus of RN writing to using individual features. That's
not necessarily a bad idea, and it definitely would make it easier to
see what features are being overlooked. We'd still need to sort the
features into beats for presentation in the RN or else completely
revamp how we format the RN.
-- 
Ben Cotton