Re: DD: Modularity guidelines

[christo@xxxxxxxxxxxxxxxxxx (Frank Christoph)]

> I expect we'll be providing stylesheets along with the documentation
> anyway.  Do you want to take the "DD Style Spec" a step further and
> make a list (or data dictionary) of commonly used variable names, such
> as "%title-font-family%", so it's easier to merge stylesheets?
> [Personally, it's far down on my priorities.]

That's an interesting idea.  Ideally, the DSSSL specification mechanism
would have included a way to control importing and exporting of names.  I
guess a "dictionary" is one way of handling these problems.  I think that
it would be good to be consistent with the use of such names (and also
with source code format/style), but that can always be edited afterwards,
and the larger idea seems a little too experimental at this early stage
(at least for my taste).

>  >   * [Topics will be written in a style that assumes complete knowledge of
>  >   the standard at a beginner's level, except for knowledge of that topic
>  >   and its dependents.  If a topic assumes a great deal of auxiliary knowledge,
>  >   though, the auxiliary topic should be cross-referenced (and it really
>  >   ought to be cross-referenced in less critical case as well, perhaps).]
> 
> This seems to assume we're doing a one-size-fits-all document.  For
> example, it's a bit hard for a tutorial to assume "complete knowledge
> of the standard at a beginner's level", and it may be hard to do a
> good description of colour spaces at a beginner's level.
> 
> If we do the beginner part properly, then there will soon be people
> wanting something more, not to mention the people already using DSSSL
> who could benefit from having examples and cookbook tips.

Yes, you're right.  I admit I threw in the "beginner" part at the end
when I realized that it isn't realistic to expect a reader to know
the entire standard at an arbitrary degree of detail, no matter how
many cross-references you include.  (I can just imagine someone clicking
away madly at hotspot links --- each time going one level deeper to find
a definition he needs to understand the current page --- until finally
he ends up where he started!)

One solution is to partition topics into classes that require approximately
equivalent amounts of experience --- say beginner, intermediate and
advanced --- and use that as the "assumed knowledge".  Then each topic
in a class assumes all the others in the class except itself, plus all
the ones in less advanced classes.

Well, ideally, that would be the case.  Realistically, we are never going
to achieve that level of organization, and, in practice, topics will not
group themselves together that neatly.

> This touches on an idea I haven't fully worked out for myself: to what
> extent does "The Project" mandate what gets written or included?  I
> don't think we can mandate anything, really.  This is a cooperative
> effort, and if people don't want to write something, they don't have
> to.  Our goal should be to collect ideas, put people who want to work
> on the same thing in touch with each other, and provide a place to put
> the results.
>
> We may be able to make a "Most Wanted" list of subject areas or types
> of documentation (or stylesheets) or outline the structure of a
> document, and the range of people able to contribute may mean we > can
> cover most things, but if someone offers something not on our list, we
> shouldn't automatically turn them away.  We should also be able to
> cope with some duplication of material (for example, two tutorials on
> the same subject that take different approaches), but I would expect
> that people would see the gaps in the mosaic and work to fill them.

Yes, even more reasons why the "assumed knowledge" scheme will not work
so well.  I also agree (or maybe I am reading too much into your words)
that it is important that The Project does not turn into some sort of
autocratic entity which dictates so much that the individual authors
have no freedom.  (Maybe some people are already looking at me out of the
corners of their eyes.  :)  Perhaps the best thing in terms of guidelines
is to keep them as loose as possible at the outset, and then introduce
consistency across contributions afterwards, i.e., editorially --- and
after obtaining consent, of course.

---
Frank Christoph                 Next Solution Co.      Tel: 0424-98-1811
christo@xxxxxxxxxxxxxxxxxx                             Fax: 0424-98-1500

 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist