Re: Update of "Features/FeatureTemplate"

On Thu, 2008-09-04 at 23:23 +1200, Amos Jeffries wrote:
> Alex Rousskov wrote:
> > On Thu, 2008-09-04 at 04:59 +0000, wiki_at_wiki.squid-cache.org wrote:
> >
> >> The following page has been changed by Amos Jeffries:
> >> http://wiki.squid-cache.org/Features/FeatureTemplate?action=diff&rev1=3&rev2=4
> >>
> >> The comment on the change is:
> >> update template to mention who things get auto-listed in RoadMap and FAQ and Priority
> >>
> >> ------------------------------------------------------------------------------
> >>
> >> = Feature: What do you want others to call this feature? =
> >>
> >> + ## Move this down into the details documentation when feature is complete.
> >> * '''Goal''': What must this feature accomplish? Try to use specific, testable goals so that it is clear whether the goal was satisfied. Goals using unquantified words such as "improve", "better", or "faster" are often not testable. Do not specify ''how'' you will accomplish the goal (use the Details section below for that).
> >
> > I think a clearly stated and concise Goal should be left for
> > documentation and historical reasons.
> >
> >> + ## Remove this entry entirely if the feature is completed and users need to know about.
> >> + ## it will then be auto-listed in the Squid FAQ.
> >> * '''Status''': What is the current status? Standard choices are ''Not started'', ''In progress'', and ''Completed''. You can specify details after a semicolon (e.g., the reason why the development has not started yet or the first release version).
> >
> > Without the Status tag, how will a person know that the feature is
> > completed and available then? Users do not know about our internal
> > rules. Will they have to interpret the Version tag?
>
> To be blunt. Yes. if a feature has no status it can be assumed complete,
> and available in one or more squid releases. The Version tag says which
> releases. The feature page should show people how to configure squid for
> the feature, so the natural assumption seeing that is its complete and
> available.
>
>
> In detail:
>
> I took a look at the RoadMap features and to me they appear to be of two
> types and two states of each type.
>
> States are: complete / incomplete.
>
> - incomplete features have things like status, and ETA clearly ident'ing
> that its incomplete. no matter what type it is.
>
> - complete features don't have an ETA.
>
> Right now the RoadMap DONE and TODO lists are where the
> complete/incomplete matters. So the presence of an ETA determines
> whether its listed as DONE or TODO on those pages.
>
> That brings us to the two types of feature: I'm calling them
> user-features and developer-features.
>
> - developer features are code bits that we developers need to base
> other stuff on. Such as AsyncCalls and BetterString. The user base won't
> care a bit whether its done or not.
>
> - user features are one the users can choose and configure. Directly
> affecting their choice of releases etc.
>
> The SquidFaq page needs a list of the user features, but not the
> developer features. Those features only need a Version, developer
> contact, and documentation suitable for users when they are FAQ listed.
> The users are likely to find the feature page off the FAQ or RoadMap so
> it needs to be documented properly anyways.
>
> What that change does, is to assume that the status is complete unless
> the status says incomplete. And also to assume that its a user feature
> if the status line is missing. Developer features are filled with code
> implementation documentation they don't care about, and should have
> status:complete left in place.
>
> Saves us from manually maintaining the feature list in the Faq.
>
> That feels very long winded for something so simple. Is it clear enough
> to understand?

Yes, although it adds one more variable into the equation: "targeted
audience" (users, developers, and perhaps distributors or others). I
agree that features differ in that aspect and that some feature
collections can include only features for one Audience.

I would prefer an explicit/direct/independent tags to strange mappings
though. Instead of making Status determine the Audience, I would add an
explicit Audience field. FAQ and other collections may want to list
"user" features that are not fully completed (or not even started!).

Kinkie has said that metadata is coming to wiki. We should not care much
about the presentation of the tags. Many of them will become invisible
or auto-rendered when metadata is fully supported. Adding new meaningful
tags is not a problem.

To summarize, let's keep the Goal and Status fields, add the Audience
field, and remove ETA fields for completed features.

Thank you,

Alex.
Received on Thu Sep 04 2008 - 13:58:53 MDT