Editor's Guide for Good Policies

Welcome to the Editor's Guide for Good Policies. Also known as Egg Pol :)

Preamble

Writing policies is not a precise science. A lot of judgement is required as to what goes in and what stays out. This question is not addressed here. Instead, this guide addresses what we do know and can control in a limited sense, so as to free us up for more judgement in what matters: the words.

References

The leading document is Policy on Policy (PoP). That document overrides everything in here, and this document only adds some detailed working practices, and amplifies PoP where useful.

To get a good feel for policy work, look at PolicyDecisions and Policy. Join the list, pick up a single policy and work your way through it.

Principles of Policy Writing

  1. There is only one policy for the Community.
    • That is, for each different policy, there is only one version that is in place at any one time.
  2. The policy group has working freedoms to draft variations.
  3. The policies are binding on all in the Community.
  4. The final word on what a policy says or means is before the Arbitrator.
  5. The Policy Group is open to all in the Community.
  6. The requirement for policies is led by Audit.
  7. Rough consensus is the metric.

Status

PoP defines three status levels for documents on the policy track:

As you will see, it is essential to understand the above three status levels to figure out anything else.

Layout of Documents

This section assumes final POLICY status. Documents not in POLICY status (WIP and DRAFT) are encouraged to head towards this formatting in their own good time.

  1. Always in simple HTML.
    • the minimum of stylistic and formatting in HTML is required.
    • this is because the documents are legally binding, and a printout of the raw HTML should be readily understandable by non-technical people (Arbitrators, Judges).
    • there must be no surprises, no hidden sections, no abilities for different meanings to emerge, and no way for people to add notes that might get confused. See P1.
  2. There is only one POLICY document. Other copies may be working documents, but they must:
    1. clearly show they are working documents, for policy group business only,
    2. refer to the real policy in loud, prominant fashion, at the top,
    3. be in live use, or be deprecated, for removal, and
    4. not be advertised beyond the policy group without care.

  3. Minutiae may be adjusted by the Policy Officer, as per p20100306.

    1. these changes must not effect the meaning of the policy.
    2. minutea include:
      • URLs, references, anchors
      • Titles
      • status of documents
      • grammatical, spelling or HTML errors
    3. PO to notify policy group on completion of changes.

Style

References

  1. References to other policies should look like:

    1. First instance is: Name In Full ("Acronym" => COD #).

    2. Later instances may use the Acronym only.
    3. Sections should be (first instance) ... Section #.# and (second instance) Acronym #.#.

  2. Internal References should be §#.# where the section symbol is entered as § in HTML.

  3. URLs may be used, but there is no requirement. If used they are over the relevant part. URLs are not part of the policy, per se.
  4. There is no particular need for a list of references at the bottom.

HTML

Use XHTML 1.1. Basic HTML symbols can be used:

  1. strong, b, em, i, cite.
  2. Headings
    • h1 is title. h2 through h5 for sections.
    • Headings should include a numbering.
    • The first section is often numbered 0 and is often called Preamble or Introduction. This is traditionally reserved for context and explanation, etc, and is of lesser importance (that is, it likely includes no text that would be important in the question of binding over the community).

    • use id="s#.#" for the anchor within the h# tag, like: <h3 id="s2.3"> 2.3 Blah blah </h3> The 's' for section is required for XHTML 1.1 which does not permit starting digits.

    • where text is tight, number and anchor the paragraphs, such as in PoP.
  3. blockquote, center, table, br, hr.
  4. Stylesheets:
    1. do not use them for policy elements (those that are binding)
    2. reserve the top, included stylesheet for WIP and DRAFT changes. It should disappear from the finished policy document.
    3. use of external stylesheets must not be relied upon.
  5. ul, ol, li.
    • Use lots of lists for good organisation of points, we aren't writing literature.

Verification

Check the document through the verifier at http://validator.w3.org/ before transferring to main site.

A standard header should include:

The best bet is to copy the header from the last changed policy. When we get control of patches and so forth, we should standardise all these.

A change list or change date is not required (but should be used in the WIP or other working documents).

Typically the ICON is also added, floating to right.

Other images. Displayed and printed versions of the document should not include any additional and distracting elements. E.g., adverts.

It's probably better not to include the verifier image or URL below, as verification doesn't work over HTTPS, and including that means we have to think about other logos (for CC, plain english, free-range eggpol...)

Storage of Documents

Index to Documents

The formal index to all policy track documents is the Controlled Document List (CDL), under CCS. Addition to CDL signals a document is on the policy track.

CDL only has the briefest information to what the document is about. It is an index, not an introduction. For broader info, see Policy.

Locations of Documents

1. Policies in full POLICY status must be stored on the main website at http://www.cacert.org/policy/ under the same regime as source code. This places them under Security Policy for control, so they are treated as patches to the source code.

For some reason, the policies are stored under the name of PolicyName.php , as a PHP program not a HTML file.

2. Working copies of Policies in DRAFT status should be stored in the SVN repository at http://svn.cacert.org/CAcert/Policies/

3. A leading version of policies in DRAFT status should be placed in the main website (as per 1. above) and marked as DRAFT, for the community's reference.

4. WIP documents can be in any form. Typically, earlier documents are on the Wiki, and they get reformatted to HTML around about the time DRAFT consideration happens.

Publishing Changes to a Policy

Once a policy goes to DRAFT, it may be submitted for publishing on the main website at http://www.cacert.org/policy/ . This is done by sending a patch to the software assessment team. Here are some instructions tuned to policy group.

  1. To prepare the patch, you need to get a local git repository. Follow the instructions on the Software/DevelopmentWorkflow to get a local repository for cacert-git.

  2. Once that repository is up and running, do git pull to bring it up to date (especially, other than the first time).

  3. cd into www/policy
  4. Make your changes to the file(s) holding the policy.
    • Note that the file should end in .html
    • you should check to make sure that URLs are changed from their SVN form; especially, URLs to policies should be relative, and reference the relative filename only.

  5. do git commit

    • quote the policy decision in the 1st line of the commit message.

  6. do git format-patch origin

    • this creates a file like 0001-my-first-change-to-a-policy-p20101225.patch
  7. send mail to cacert-devel
    • brief explanation
    • subject line to include the Subject from the patch
    • attach the patch file.

Note that the policy decision authorises the publication of the policy, but the Software Assessor has to check over the patch itself.

Making Decisions

Work Flow

Signalling Changes and Comments

Changes must be signalled clearly when inserted into a DRAFT policy document. A summary of working changes should be included, clearly separate from the policy.

Changes suggested should be signalled in BLUE. Text to be struck out should also be struck-out with a horizontal line across that text.

Commentary should be in GREEN. Commentary is never part of the policy.

See the style sheet examples in the beginning of the SVN policies for examples of HTML.

Rough Consensus

Decisions are made according to rough consensus, a concept borrowed from IETF http://www.cacert.org/policy/PolicyOnPolicy.php#s2.3.

Rough consensus is somewhere between a unanimous acceptance, and a clear super-majority. A simple majority vote of 51% is not sufficient, and a 100% vote is not required.

In practice this means that all criticisms must be addressed sufficiently to be satisfied that all have had a fair say. But it also recognises that there will always be some who disagree. Perfect is the enemy of the good, and PoP and DRP give the possibility of fixing up errors in the future.

Voting on Decisions

Where a decision is important (e.g., has binding effect on the Community) or is controversial, it should be a voted decision. A voted decision will better support future Arbitrations.

Votes are called by proposing a resolution on the policy group maillist. Anyone can propose a resolution, but it is generally better to discuss it first.

Allow at least a week to collect votes, and up to 4 weeks for a difficult decision. If there is movement towards a conclusion, the vote can be extended. The time should be well signalled.

Changes will likely emerge during the voting period. Non-controversial changes (wordings, mistakes) can be incorporated without fuss. Changes that have more impact should be discussed, and if supported by consensus inserted into the document. Consider pinging the voters, and adding more time.

Recording of Decisions

The proposition, the Votes and the Decision Number are recorded on the record at PolicyDecisions. Either a reference to who, or the thread can be used. Including the Names is beneficial because it recognises the hard work that people put in to the policy work.

The Decision Number is defined on DecisionNumbers and is a 'p' followed by a date. Generally this is the date by which the resolution is first proposed, not the date the vote closes. The date of effect is not defined (which means it is up to the Arbitrator in any dispute).

Authority

Source of Authority. The Policy on Policy is the formal document that gives the Policy Group the mandate to pass policies that are binding on the Community.

Scope. Which documents become policies is defined by the Audit process and more particularly DRC-A.1 which defines a set of formal documentation required by the CA. DRC-A.1 mandates the creation of a Configuration Control Specification or CCS (now in DRAFT). A large part of CCS is policies, which themselves are controlled by the Policy on Policy. 

      Audit => DRC => DRC-A.1 => CCS => PoP

Documents that are required by audit, or are deemed to be required by audit by management, are termed policies. These Documents get a COD number under the CAcert Official Document scheme which is kept in the Controlled Document List.

Exceptions. There are two significant exceptions to this authority outside Policy Group. Firstly, the Board may veto an entire policy in DRAFT, so as to deal with policies that in its view impose unacceptable conditions on the Association. However, once the policy moves to POLICY, that exception is lost. Secondly, all disputes are referred to CAcert's Arbitration. Hence, these two exceptions provide substantial before and after protection.

Origins. This role was previously held by the Board of CAcert, Inc. up until the 2007 Pirmasens TOP. At that meeting the Board approved the three key foundational documents (PoP, DRP, CCA) into binding effect. By approving PoP to DRAFT, the Board passed the control for voting policies into binding effect to the Policy Group. The key foundational documents were later ratified by the Association's general meeting, as well as being confirmed into POLICY by the policy group itself. These documents work together to create a strong governance foundation for the community and the rest of the policy documents.

Miscellaneous

Language

English is the language of CAcert policy, as it is the baseline for all Disputes before Arbitration.

There is a preference for Australian English. This is almost the same as British English, and can be considered equivalent. The main difference between this English and the North American version is that there are some simplified spellings in North American English.

When writing, prefer plain and simple English, as most in the community do not have English as a first language. Try to rewrite sentances when they get complicated. Use shorter expressions. Use small words :) Add more punctuation (North American English tends to strip out commas).

CAcert policies do not try and hide the difficult areas, instead they try to solve difficult areas and surface them when we cannot solve them.

Although Translations are possible, they are not recommended in most cases. Problems include: a lot of work; a tendency to get out of date (changes move faster than translations into all languages); and they lead to incomplete understandings due to errors in translation.

Gender. The general way to use gender in the policy documents is to use the cryptographic conventions first described in the RSA paper. Ref: wikipedia. In this method, each party receives a name, which implies a gender. Alice is first, Bob is second, Carol is third, etc. In CAcert community, we generally say that Alice is the Member and Bob would be the Assurer. Note that this is a convention adopted as a practice but is not policy.

Non-Policy Documents

Other documents that are useful but outside that scope should be named by other labels, so as to not confuse. For example: Manual, Guideline, Practices, etc. Where applicable, a policy may mandate the creation of these documents.

RELIANCE

Because we are in the PKI and CA business, the terms RELY and USE are often capitalised to signal their special meanings. Variations include RELIANCE and USAGE.

(Their meaning is not defined here. See CPS, CCA.)

IETF

Note that some ideas have been borrowed from the IETF RFC process. Notably, "rough consensus" is used, but is as described above.

The terms "must, should, may" are generally used with IETF RFC2119 meanings, but are not capitalised (see above on RELIANCE).

However, these practices do not imply that other parts are assumed from IETF; our own processes have evolved independently, and only a little has been borrowed.

Intellectual Property

From PoP, all contributions to CAcert's policy work are transferred by ownership or by full licence to CAcert Inc (PoP 6.2). That means, if you make a comment on the maillist, or post on the wiki, or share commentary in private email with those working on the policies, those words and ideas can be used.

Licence

CAcert in its turn (PoP 6.4) licenses the documents out in a free and open licence Creative Commons - Attribution - ShareAlike 3.0 Australia with all disputes referred to our Arbitration under DRP. This is better known as CC-by-sa, or more fullsomely as CC-by-sa-3.0-AU+DRP.

Editorial

Reference. In order to reference the licence in the text, use this form (all as one line) in the title block: 

Licence:
  <a href="wiki.cacert.org/Policy#Licence"
  title="this document is Copyright CAcert, licensed openly under CC-by-sa with all disputes resolved under DRP.  More at wiki.cacert.org/Policy" >
  CC-by-sa/DRP </a>
  <br />

Note that the reference line is a work-in-progress.

Spelling. The British/Australian English spelling of licence is used: licence is the noun, and to license is the verb.

Acknowledging Your Contribution

Currently there is no way to acknowledge your contribution to a policy within that policy. Sticking a copyright notice into the text doesn't do it, because as above, the content is transferred automatically.

To review

Style and Format

These are documents that do not relate to Audit, but for historical reasons followed part of the policy track.

To be looked at

Old, out of date

Policy/Guide (last edited 2016-05-31 12:54:51 by AlesKastner)