6:29 p.m.
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_...
[2] http://fedoraproject.org/wiki/Category:Documentation_beats
--
-- Pete Travis
- Fedora Docs Project Leader
- 'randomuser' on freenode
- immanetize(a)fedoraproject.org
5:52 a.m.
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
9:04 a.m.
----- 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(a)lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
9:07 a.m.
On Tue, Jan 29, 2013 at 7:29 PM, pete <me(a)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
9:54 a.m.
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
4077
days inactive
4110
days old
4 comments
4 participants
participants (4)
-
Ben Cotton -
Jaroslav Reznik -
John J. McDonough -
Pete Travis