Recommendation for the procedure to add platform packages
duncan.coutts at worc.ox.ac.uk
Sun Aug 23 15:31:17 EDT 2009
I'll try and summarise the concerns that Ian has raised:
* That documentation written for the proposal will get lost.
The "how to" says that if people write a new API intro, then it
should be integrated into the haddock docs or saved on a project
Ian thinks this suggestion/advice is not sufficient to ensure
that the docs do not get lost and thinks that some procedural
device is necessary.
Ian thinks that the best mechanism is to require the API intro
be a separate doc that is linked from the proposal. Thus the
proposal authors would not have the opportunity to "improve" the
docs for the proposal without those improvements also being
saved as part of the package.
Ian accepts that there may be other mechanisms to make sure docs
written for the proposal do not get lost but would have greatest
confidence in the method he suggested.
* That the package proposals would be too long and too wordy.
There are a few aspects to this:
1. That text included inline in the proposal is less
readable than the same amount of text in separate
documents linked from the proposal (like API intro);
2. That the "rationale" suggested in the "how to" and
example is mostly redundant/unnecessary;
3. That things described in words could be summarised by a
"yes" in a checklist.
Specifically that a checklist augmented with text sections is a
shorter and better proposal format than a free-form proposal.
Related to this is a belief that the criteria for inclusion can
and should be reduced to evaluating a list of requirements. Some
of those requirements would be objective, some subjective, but
all relatively specific. Passing all requirements would be the
criteria for inclusion.
* That the policy document itself is too long and too detailed.
That it anticipates eventualities that may or may not arise in
That the overall length is a problem because it is off-putting,
with the danger that people simply will not read it.
Ian, is this a fair summary? Is there anything I've missed that I didn't
address specifically in the previous email?
More information about the Libraries