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:
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.
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. - Ensuring the content of the Feature is understandable by a hypothetical average user. - Working up a basic guide to implementing the feature, if applicable. - Creating an entry for the Feature in the appropriate Release Notes beat. - 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?
[1] http://fedoraproject.org/wiki/Releases/19/FeatureList#Fedora_19_Accepted_Fea... [2] http://fedoraproject.org/wiki/Category:Documentation_beats
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
----- Original Message -----
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").
Hi, I'm going to reopen this discussion again - with more details available now. FESCo agreed on the feature process revamp [1] - we are now trying to plan the release and actually separate the planning/tracking from marketing side. Features process is now going to be called Planning process (even I'm not sure we have ever call it Features process ;-) and feature will become "changes". And real features will be created based on the list of changes - it's the idea for now, looking for your - docs and marketing teams input.
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.).
So what I can offer you here - we could join the effort here, not to duplicate amount of the work. We are definitely going to change how feature pages will look, how feature list would look too and here I see an opportunity to have one common place. Btw. we (me/FESCo) are still thinking what tool to use, wiki is suboptimal for this task, ideas are Bugzilla, Trac (but I've already mentioned this in my first reply)...
[1] https://fedoraproject.org/wiki/User:Mmaslano/Feature_process
Jaroslav
[1] http://fedoraproject.org/wiki/Releases/19/FeatureList#Fedora_19_Accepted_Fea tures [2] http://fedoraproject.org/wiki/Category:Documentation_beats
-- docs mailing list docs@lists.fedoraproject.org To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
On Tue, Jan 29, 2013 at 7:29 PM, pete me@petetravis.com wrote:
- Ensuring the content of the Feature is understandable by ahypothetical 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.
On Wed, 2013-01-30 at 10:07 -0500, Ben Cotton wrote:
We'd still need to sort the features into beats for presentation in the RN or else completely revamp how we format the RN.
What if the feature champion was required to add a link to the feature on the appropriate beat page? We could still shuffle the links if they didn't make sense, but it would sensitize the feature writer to the need for a functional description, and also make him aware that there is a beat writer somewhere who is going to be snooping around?
--McD
docs@lists.stg.fedoraproject.org
-
Ben Cotton -
Jaroslav Reznik -
John J. McDonough -
Pete Travis