[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.
Wouter van Vugt