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:

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 page. I'm not sure what is required here, but some thoughts:

  1. editor
  2. COD# (see next point)
  3. short name, long name
  4. 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:

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:



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 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 and start hacking the PHP.

Documentation/WishList (last edited 2011-05-13 09:19:37 by UlrichSchroeter)