Hi all,
Weighing in a bit late and a bit light - apologies.
First off, it's good to have the Singapore Framework expanded and discussed more fully.
My main concern is what should a guidelines document be/contain? This version works well as a tutorial but not as guidelines.
I would expect guidelines to:
a. List options and the best practices from those options
b. Be easy to scan using technical documentation writing techniques (I found it obliged you to read it from one end to the other and left it to the reader to determine the recommended practice)
c. Provide checklists so I can see whether I comply with the guidelines.
As a real-life Application Profile creator, I'm still confused whether what I have done follows DCMI best practice or not according to these guidelines.
I think the majority of the content is there (except the usage and syntax sections are light, e.g. there is no discussion on how to publish the AP, or that I should), it just needs distilling and reformatting, eg. maybe each section could have subheadings: overview, definitions, guidelines, examples, worked example.
Also, it seemed to spend a lot of time explaining how the DCAM and Description Sets work (as you'd expect in a tutorial) instead of which aspects should be applied and in which situations.
A more particular comment is that how to define new terms is in an appendix - I would have expected a brief overview in section 5 before linking to the appendix. I realise defining new terms is to be discouraged, but it often must be done and it would be useful to get a quick idea of what's involved (eg "you will need to decide on the types of values expected, encoding schemes to use, a namespace, etc.").
Thanx,
Douglas Campbell
National Library of New Zealand
|