Re: [Techs] Divide Techniques docs into chapters?

On Wed, 13 Apr 2005, John M Slatin wrote:

>
> One suggestion was to adopt anapproach similar to the I18N group: put
> important user agent information at the beginning of each technique, so
> readers could decide right away whether to bother reding that technique
> or not.

An alternative would be to state at the beginning of each technique
in which baseline or baselines it was supported, then to provide user
agent information for each baseline in a separate section, including any
qualifications needed in relation to specific techniques.

>
> I had a thought about dividing the larger Techniques documents into
> chapters corresponding to the three "baselines" that have been proposed.
> I took an action item to write it up, so here it is.  There really isn't
> much more to it than that.  On this model, each Technology-specific
> Techniques document would have three chapters (or call them Sections if
> you prefer).   Each chapter or section would cover one baseline (e.g.,
> Basic, Transitional, Advanced or whatever).  All the techniques that
> could be used for each of the baselines would be contained in the
> chapter for that baseline.  Each chapter could begin with an Overview
> section that would describe the baseline and considerations relevant to
> it.  A good deal of user agent information could be addressed in this
> Overview section.

My concern here is that many of the techniques may turn out to be relevant
to all three baselines. You would either have to duplicate this
information for each baseline, thereby lengthening the document
unnecessarily, or provide lots of cross-references to techniques described
in connection with one baseline that are also applicable to the others.

>
> The possible advantages to this approach are:
> - might avoid duplicating large quantities of UA information in multiple
> techniques (and might therefore be easier to update as UA situation
> changes);

This can be achieved by assigning each technique to one of the baselines
and maintaining the UA information separately. If someone decides they're
going to write to one of the baselines, they won't need detailed UA
information after making that decision, but they will need it in order to
decide in the first place, which is why it would make sense to maintain
this material in a separate section of the techniques document.
> - could give developers a clearer view of what a given baseline does or
> doesn't allow for.
The same with a separate section on baselines.
>
> Possible disadvantages:
> - Putting the UA information up front might make it esier to skip over,
> and might also work against providing the granular detail that might be
> needed in some cases;
How would this happen exactly?
> - collecting all techniques relevant to baseline X in chapter X might
> unintenionally limit developers' creativity; they might not become aware
> of something in a different chapter that might work for them, either for
> the site they're working on right then or for some future project;
Yes.
> - might give *us* a false sense of completeness.
>
Given the collective analytical prowess of the techniques task force and
the working group as a whole, that's a pretty distant prospect!

To clarify, I am not trying to oppose John's proposal here; if it turns
out that in most cases it wouldn't lead to massive duplication of
information then it's a perfectly fine proposal.

Received on Thursday, 14 April 2005 05:39:36 UTC