Documentation issues, brain dump v1.1
Style within HTML for Controlled Documents
1. Are we all agreed then that HTML is the basic format for controlled documents? If so, then the question is the precise form of HTML: some version, list of tags, etc. This task is well under way in other thread for style guide, excellent stuff.
2. Decide on the format/layout template for HTML doco so they all look similar and have the same meta-info in them.
Currently there are two, the one used on older Policies and the more recent one, e.g., AP.
(Whether there is a real preference for either of them is an open question. The real need is to identify one of them, and have editors stick to it. Whatever it is, it should be minimal, simple and have no tricks in it like fancy gfx, javascript, what-have-you.)
PoP states some things about this question, as it lists the minimum meta-information. Also, there was an informal/M-SC decision a while back that Authors were not to be listed, only a single Editor.
3. Once decided, migrate all DRAFTS and POLICYs to that format.
Locations for documents heading to POLICY
Decide (or reach consensus) on the preferred location for all three phases for each doc. Currently it is:
POLICY: www.cacert.org/policy/ It is very important as a confirming signal that this be clear and solid, which is why POLICY documents go on the website and others do not.
DRAFT: no clarity yet. Some think that DRAFTs should go on the main website. I think not because that is too hard to manage and the signal sent to people who look at the website is confusing. Also, some think that the DRAFTs should go from wiki to SVN ... benefit is that at some stage the document has to go into HTML form, so this is as good a time as any. Minuses: (a) we have to change all the links to it, and (b) we need a new group of editors and authors who are competent in both forms: SVN and wiki.
WIP: these can go anywhere by definition, but there is some sense of them as being under the wiki /PolicyDrafts/ or on the svn /Policies/ . Either way there should be an easy way to catalogue the location of all wip & draft policy work.
Tools to make sharing the work better
Investigate tools to do better shared work / commentary, etc.
Meta-Information for the POLICY page
Create some sense of meta-information for the http://www.cacert.org/policy/ page. I'm not sure what is required here, but some thoughts:
- editor
- COD# (see next point)
- short name, long name
- description
It could be a simply PHP script. Either way, the URLs should be preserved, we need those URLs to be reliable.
Formal Referencing Convention
We need some formal referencing fashion that works with:
- HTML documents (so href links)
- printed documents
Controlled documents (like COD numbers in OfficialDocument)
- short names like CPS, CCA.
- long names in full "CAcert Community Agreement."
It might be that which is in the cps, like this:
Certification Practice Statement (CPS => COD6) |
where some part of it becomes a href link:
Certification PS.. (<a href="">CPS => COD6</a>) |
which should then appear in all the docs whenever a formal/controlled/oficial document is referenced.
It should have a "first introduced in full" form and a "2nd short form" where the second form might be like:
CPS (COD6) |
etc.
Move PP
The Privacy Policy needs to move from its current location (link on main page, bottom, part of the CMS) to /policy/ in some fashion. The CMS entry should disappear and the document should be placed into the /policy/ page in the same format as the others. This will require a link update (below).
Best bet is that the document is moved without any change to the content. If we look into changing the content, it will never move ... major job.
Link updates in wiki
Link update: Links are out of date for AssurancePolicy. As it has moved from wiki to SVN we have to change every link in the wiki to refer to it, and also check all other places to see if there are any links.
Any need for derivative printable forms (ODT, PDF) ?
Decide whether we have any need for ODT and PDF forms of the policies.
It is unclear what the need is. Minuses: multiple versions runs the risk of multiple "policies", which will create a foodfight in Arbitration one day.
ODT was a distraction. PDF can be done by the browser.
Plus: Pagination. IMHO: that's not worth it if it means we have end up with multiple copies.
Old stuff on Wiki
Wiki: lots of old stuff. Where it is found, put deprecation notices up on top and references to the new current pages. Where possible, incorporate good stuff to the new pages. Where clear, delete the page.
Old stuff on WWW
WWW: lots of old stuff there too. Scan and identify what needs changing, deleting, over to wiki. Update the list of changes at RolloutCommunityAgreement or start another list as applicable.
Any *really critical changes* (that is, has legal ramifications or similar) we need to identify and then ask sysadmin team to fix. This however should be limited to the absolute essentials. "Our website looks crappy" isn't good enough 
until we get some developers who can get onto the code on test.cacert.org and start hacking the PHP.