Recommendation for the procedure to add platform packages

[Duncan Coutts]

All,

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
        home page.
        
        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
        practise.
        
        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?


Duncan