## 20160531 AK
----
[[Policy/Guide/CZ|česky]] | '''english'''
----
## page was renamed from Brain-Policy/Guide
= 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 ([[http://www.cacert.org/policy/PolicyOnPolicy.php|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.
1. The policy group has working freedoms to draft variations.
1. The policies are binding on all in the Community.
1. The final word on what a policy says or means is before the Arbitrator.
1. The Policy Group is open to all in the Community.
1. The requirement for policies is led by Audit.
1. Rough consensus is the metric.
=== Status ===
[[http://www.cacert.org/policy/PolicyOnPolicy.php|PoP]] defines three status levels for documents on the policy track:
|| status || nature || forum of challenge || location || comments ||
|| '''POLICY''' || binding || arbitration || [[http://www.cacert.org/policy/|cacert.org/policy/]] || in plain HTML only, [[Brain/PoliciesAndSignificantTechnicalStandards/CompletedPolicyOverview|Overview]] ||
|| '''DRAFT''' || binding || policy group, arbitration, board || [[https://svn.cacert.org/CAcert/Policies/|svn.cacert.org/CAcert/Policies]] || conversion to HTML generally required for vote, must be version controlled, [[Policy/Tasks|task list]] ||
|| ''work-in-progress'' || non-binding || policy group || typically, on wiki, moving to SVN when approaching DRAFT || ''wip'' for short. This is a status identifying it for policy track, but otherwise it is "uncontrolled" [[Policy/Tasks|task list]] ||
|| ''deprecated'' || non-binding || policy group || typically, on''work-in-progress'' documents that have been dropped in preference for other approaches || This is a status identifying a historical document that is no longer being pursued, but might be interesting for ideas. It '''is not defined''' in [[http://www.cacert.org/policy/PolicyOnPolicy.php|PoP]], rather it is adopted by policy group as a convention. ||
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.
1. There is only one POLICY document. Other copies may be working documents, but they must:
a. clearly show they are working documents, for policy group business only,
a. refer to the real policy in loud, prominant fashion, at the top,
a. be in live use, or be deprecated, for removal, and
a. not be advertised beyond the policy group without care.
1. Minutiae may be adjusted by the Policy Officer, as per [[PolicyDecisions#p20100306|p20100306]].
a. these changes must not effect the meaning of the policy.
a. minutea include:
* URLs, references, anchors
* Titles
* status of documents
* grammatical, spelling or HTML errors
a. PO to notify policy group on completion of changes.
== Style ==
=== References ===
1. References to other policies should look like:
a. First instance is: Name In Full ("Acronym" => COD #).
a. Later instances may use the Acronym only.
a. Sections should be (first instance) ... Section #.# and (second instance) Acronym #.#.
1. Internal References should be §#.# where the section symbol is entered as § in HTML.
1. 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.
1. There is no particular need for a list of references at the bottom.
=== HTML ===
Use XHTML 1.1. Basic HTML symbols can be used:
a. strong, b, em, i, cite.
a. 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: '' 2.3 Blah blah
'' 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.
a. blockquote, center, table, br, hr.
a. Stylesheets:
i. do not use them for policy elements (those that are binding)
i. reserve the top, included stylesheet for WIP and DRAFT changes. It should disappear from the finished policy document.
i. use of external stylesheets must not be relied upon.
a. 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.
=== Header ===
A standard header should include:
* Short Name + COD Number
* Editor, where selected
* Status (WIP, DRAFT, POLICY).
* This is also done with an Icon from /images/ below (note must be lower case).
* Decision Number for current status
* Licence as now standardised under [[PolicyDecisions#p20100722|p20100722]]
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.
||{{http://www.cacert.org/images/cacert-policy.png}}||{{http://www.cacert.org/images/cacert-draft.png}}||{{https://svn.cacert.org/CAcert/Policies/images/cacert-wip.png}}||
* '''XXX Change''': unify the image directory names above to:
* __(/policy/images/cacert-XXX.png)__
* '''XXX Change''': The header should be standardised across all policies but is not as yet.
'''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...)
|| The verifier icon local copy||The verifier icon via link URL||The verifier icon URL itself||
||{{attachment:valid-html401-blue.png}}||{{https://validator.w3.org/images/valid_icons/valid-html401-blue.png}}||https://validator.w3.org/images/valid_icons/valid-html401-blue.png||
== 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/
* to support the work of the policy group in taking them to POLICY.
* to support the transition to HTML.
* These copies may include WIP changes, clearly signalled (e.g., blue).
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.
* As and when the policy group passes through changes to DRAFT, the Policy Officer should update the primary copy.
* It must not include any WIP changes.
''' NOTE: this above represents a change to procedures. '''
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.
1. Once that repository is up and running, do ''git pull'' to bring it up to date (especially, other than the first time).
1. cd into www/policy
1. 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.
1. do ''git commit''
* quote the policy decision in the 1st line of the commit message.
1. do ''git format-patch origin''
* this creates a file like 0001-my-first-change-to-a-policy-p20101225.patch
1. 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 ===
* The Policy work process is controlled by [[http://www.cacert.org/policy/PolicyOnPolicy.php|Policy on Policy]], which describes what is meant by the status WIP, DRAFT and POLICY.
* The current task list is at [[Policy/Tasks|Tasks]].
* Work on new policy is undertaken in several places:
* Discussion and decisions on policy document status are taken on the [[https://lists.cacert.org/wws/info/cacert-policy|Policy email discussion list]]. CAcert Community Members are invited to join the list and participate in these discussions and decisions.
* For an overview of past work, see the list of [[PolicyDecisions|policy decisions]].
* Many policies take form in meetings, such as [[https://svn.cacert.org/CAcert/Assurance/Minutes/20091215HamburgMiniTOP.html|Brussels]].
* These controlled documents are listed / managed in [[http://svn.cacert.org/CAcert/Policies/ControlledDocumentList.html|Controlled Document List (CDL)]] and made available on the [[http://www.cacert.org/policy/|Policy web page]] on the CAcert http://www.cacert.org formal web site. Policy Officer keeps this up to date, following the [[PolicyDecisions|policy decisions]]
* [[PolicyOfficer]] is an appointed person who can organise, make minor changes, push along the documentation, and keep [[http://svn.cacert.org/CAcert/Policies/ControlledDocumentList.html|CDL]] up to date. Also see [[DocumentationOfficer]], who can prepare standards for documents, and re-org the archives for utility.
* [[PolicyDrafts/FAQ|FAQ on Policy]] - frequently asked questions on Policy work.
=== 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 [[http://www.cacert.org/policy/PolicyOnPolicy.php|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 [[https://svn.cacert.org/CAcert/Policies/ConfigurationControlSpecification.html|Configuration Control Specification or CCS]] (now in DRAFT). A large part of CCS is policies, which themselves are controlled by the [[http://www.cacert.org/policy/PolicyOnPolicy.php|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 [[http://svn.cacert.org/CAcert/Policies/ControlledDocumentList.html|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|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. [[http://en.wikipedia.org/wiki/Alice_and_Bob|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 ([[http://www.cacert.org/policy/PolicyOnPolicy.php#s6.2|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 ([[http://www.cacert.org/policy/PolicyOnPolicy.php#s6.4|PoP 6.4]]) licenses the documents out in a free and open licence [[http://creativecommons.org/licenses/by-sa/3.0/au/|Creative Commons - Attribution - ShareAlike 3.0 Australia]] with all disputes referred to our Arbitration under [[http://www.cacert.org/policy/DisputeResolutionPolicy.php|DRP]]. This is better known as CC-by-sa, or more fullsomely as CC-by-sa-3.0-AU+DRP.
* The licence form was chosen in [[https://community.cacert.org/board/motions.php?motion=m20100815.1|m20100815.1]] after being advised by policy group in [[PolicyDecisions#p20100722|p20100722]].
* See [[PolicyDrafts/DocumentLicence|older discussions on choice of licence]].
* The point of adding DRP to the CC licence is that our dispute resolution is far more cost-effective and trans-national. No dispute resolution is indicated in the CC licences. This obviously gives us an advantage in any dispute, but that's fair enough given the ownership and work done so far. Also, disputes in such an area are not really expected, so our fast and effective system will work well.
* '''Brand.''' The offering of CC-by-sa by CAcert '''does not imply any licence to use the brand name of CAcert''', except in the direct context of CAcert's community work. This means that if you use a policy or elements of it outside the context of CAcert, then you must also change the use of the brand to your own brand (saving for a clear acknowledgement of the source of the text).
==== Editorial ====
'''Reference.''' In order to reference the licence in the text, use this form (all as one line) in the title block:
{{{
Licence:
CC-by-sa/DRP
}}}
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.
* ''There may be a case for changing this.''
* ''Experience in IETF work has not been kind, in that accurate measurement of contributions has been criticised.''
* There is a screen-scrape of [[https://svn.cacert.org/CAcert/Policies/policy_group_decisions_summary.html|Contributors to voting and decisions]]. This however does not cover drafting and editorial.
== To review ==
=== Style and Format ===
These are documents that do not relate to Audit, but for historical reasons followed part of the policy track.
* The Brand and House Style guide ([http://svn.cacert.org/CAcert/Documentation/COD/PDF/COD12.pdf COD12) describes the logo, and CAcert house styling.
* Brand, name and logo are owned by CAcert Inc.
* The House Style guide is accepted by the Board on 13th of December 2007.
* It has however never really gained traction.
* It should be reviewed and considered for incorporation into [[Policy/Guide|EggPol]].
* an older attempt at format is from [[http://svn.cacert.org/CAcert/Policies/DocumentsPolicy.html|Documents Policy]] (COD3, wip only). However this document was never really presented nor discussed. Ditto above.
=== To be looked at ===
* [[http://wiki.cacert.org/wiki/PolicyDrafts/?action=fullsearch&context=180&value=PolicyDrafts&titlesearch=Titles:wiki|documents]]
* see [[Policy/FAQ|the FAQ]] for more info.
=== Old, out of date ===
* [[PolicyDrafts]] was the original location of the working list of Policy work. It was misnamed. Moved to [[Brain/PoliciesAndSignificantTechnicalStandards/PolicyDRAFT]]. Still misnamed.
* [[PolicyDiscussionsOverview]] was a 2008 view on status. Now out of date, but could be brought up to date.
----
. CategoryAudit
. CategoryPolicy