[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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
|
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]