Re: Update of "Features/FeatureTemplate"

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?

Amos

-- 
Please use Squid 2.7.STABLE4 or 3.0.STABLE8