Re: Documenting Features
On Tuesday 29 of January 2013 17:29:47 pete wrote:
Hey guys,
I've been reading the Feature discussions on devel@ today, and an idea
came to mind. A process for documenting accepted Features would help
prevent major changes from slipping through the cracks. Here's what I
came up with so far; I think we can hammer it into something useful:
Hi Pete,
thanks for kicking this off - I've been overflooded with all features coming and
I did not have time to start it (actually I had time, but mentally ;-).
At FUDCon we had a long discussion how the feature process should look like
and the result is - we would like to do the real proper planning and tracking
of features (so it will be Planning process, not feature process - even we
could find some other name?) and split it from marketing side - so only a
subset of these proposals will be featured (and thus it's the word
"feature").
Accepted Features[1] will be listed in a table roughly analogous to
that
used for Release Note Beats[2]. The table would have columns for the
Feature name, a docs volunteer, and developer contact, as well as others
reflecting the Feature documenting workflow.
Believe me - maintaining even FeatureList is a big pita - but speaking about
tracking of development and splitting marketing - this could be done on the
main FeatureList - I'm definitely open to any suggestions from documentation
team how to enhance FeaturesList to work for you - as we really want all
planning/tracking to happen in one place (and definitely not anything that's
out of sync often etc.).
One idea is to try to use some other tool than plain wiki - that's not very
suitable for this task (but with more parsing scripts...). But at least
there's huge resistance to Trac at least in FESCo ;-)
A set of guidelines for the docs volunteer covering a feature will
come
along with the table. The set of tasks to be juggled might include:
- Establishing an appropriate developer point of contact to aid in
documentation. Note that this isn't always the feature owner.
But mostly it is Feature owner (but anyone willing to help could be added to
Owner section as "Developer contact").
- Ensuring the content of the Feature is understandable by a
hypothetical average user.
This is something I'm not sure based on the split we want - as we really need
technical details for planning features and that users/press part should be
processed differently (and aim on the user).
- Working up a basic guide to implementing the feature, if
applicable.
- Creating an entry for the Feature in the appropriate Release Notes
beat.
+1, again - more features = more data for RN
- Checking existing guides for impact caused by the new Feature,
filing
bugs as needed, and assisting the guide owners in updating as
appropriate.
A defined process like this will help split up the workload caused by
feature churn and cut redundant efforts by providing new information for
multiple published works. Your thoughts?
It's a good idea to have a good source for multiple published works in the way
- FeatureList for tracking (RNs, docs) etc -> pick up spotlight Features (we'd
like to Feature) -> Announcements are for free, leaflet for media is for free,
ambassadors...
Btw. I understand that we can never split the feature process completely, and
there will be always people using the internal planning/tracking process for
articles etc. - we are open project and we will never hide any kind of
information. But FreeBSD kernel is a good example how it works :)
I'm CC'in marketing team for feedback.
Jaroslav