Re: review of Document Overview

From: Ivan Herman <ivan@w3.org>
Subject: Re: review of Document Overview
Date: Sat, 04 Apr 2009 11:07:50 +0200

> Sandro Hawke wrote:
>>>>>> 2.4/ Profiles:
>>>>>> Remove Figure 2, as it serves no useful purpose.
>>> I'm baffled as to what purpose you think this figure serves and why
>>> its loss will be mourned. AFAICT, the information content of the  
>>> figure is:
>>> ...
>> 
>> It's not intended to provide additional information; it's about
>> presentation.  It's intended to make the relationship between the
>> profiles feel as simple as it actually is.  A simple-looking diagram
>> conveys that feeling much more effectively, I think, than the text.
>> 
>> But perhaps that's just me, so I'm okay with letting it go
> until/unless
>> others speak up for it.
>>
> 
> I have been looking at the flood of mails on one single diagram, gave
> some thinking and, after all, I decided to speak up for it, too
> (although, I must admit, I was not sure about it for a while).
> 
> I think that the argument on whether the diagram gives additional
> information or not is besides the point. Obviously it does not, just as
> none of the diagrams do either in this document or the others, except
> for the 'official' UML diagrams. But let us accept the fact that for
> many people a diagram helps in understanding things, relationships and
> makes it easier to follow than a succinct (though precise) text. (I am
> certainly one of those, after all, I spent most of my research years in
> computer graphics and visualization and not in web technologies.) I
> would actually be pleased to have _more_ diagrams in the spec documents,
> too, even if they would not add any new information and therefore would
> not serve a useful purpose specification wise.
> 
> If this diagram is not _false_ (which I do not think it is the case), I
> would propose to leave it in. It does not harm, and it may help. What is
> the big deal?
> 
> Ivan

Every extra "bit" of a document adds harm.  Remember, "less is more"!
To offset that harm the "bit" should make a significant improvement to
the document as a whole.  This is especially true for figures, which, by
their very nature, are very much more "in your face" than text.

I don't see any advantage to Figure 2.  Aside from the fact that it
only reiterates what is said in the text, Figure 2 also thrusts into the
limelight things that should not be there.  For example:  What are the
four unnamed intersections in the document?   Is EL about half the size
of DL?  Is DL about half the size of Full?  Why the odd "OWL 2 (Full)"
construction?   Is Figure 2 as important as Section 3.1?

peter

Received on Saturday, 4 April 2009 18:00:55 UTC