Improving spec readability through restructuring content

Now that I am reading the ODF spec in more detail I have seen a
recurring pattern. It is a pattern which hinders readability and could be
easily improved. Here's the deal. 

Take the ZIP package structure as a sample. In the ODF 1.2 spec
(I use draft 6) you find that the ZIP structure is discussed in chapter 2 of
part 3. (yes, the ODF spec is moving into separate parts just like Open XML).
However, some important bits of information are not there. Each ODF document
uses a concept called document roots as a starting point, and spreadsheets,
documents and presentations use the same roots. Each root is stored in a
separate file in the package. Since these files are common to all documents,
and vital for understanding ZIP packages, you would expect the details to be
available in the chapter on package structures. Instead this information is in
another part of the spec (part 1, chapter 2.2 Document Representation). Now one
might argue that the package and the files contained within are two different
concepts, and perhaps if the ODF concept of a package is more elaborate (say,
like the Open Packaging Convention of Open XML) this might be a valid point.
But for the current state of ODF, package means that there are these 4 roots,
always in the same location. To me it was hard to find this, since I looked in
the packaging information, not anywhere else. 

Something similar occurs in another area. This time the issue is
with encryption. Encryption is discussed in chapter 2.3 of part 3. However, the
fact that preview thumbnails are never encrypted and have a special process is
not mentioned. Instead that is mentioned not in the part on encryption, but in
the part on thumbnails. Logically I will never see that part on thumbnails when
I try to decrypt a document. It is not on my scope and I expect to see all
relevant info in the right place. 

So, I propose improving the structure of the spec by
consolidating the information into more logically correlated blocks. 

 

 

Best regards, 

 

Wouter van Vugt

MVP Visual Studio Tools for Office

 

  
  

  
  
  


  
 

 

  
  

  
  
  
+31 6  438 317 12

  
 

 

  
  

  
  
  
@woutervugt

  
 

 

  
  

  
  
  
http://blogs.code-counsel.net/wouter

  
 

 

 

  
  

  
  
  
Code
  Counsel

  
  
  
Critical Path Training

  
  
  

  
 

 

  
  
Sharing
  Knowledge with Passion

  www.code-counsel.net

  
  
  
Your fastest way up the SharePoint learning curve!

  www.criticalpathtraining.com