Documenting Features

[Jaroslav Reznik]

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

> [1]
> http://fedoraproject.org/wiki/Releases/19/FeatureList#Fedora_19_Accepted_Fea
> tures [2] http://fedoraproject.org/wiki/Category:Documentation_beats