Outdated Documentation

You are getting them jumbled because they are all inter-related.

So, to be clear, I am NOT just talking about community documentation. I am talking about ALL documentation.

Let me outline a little of the kind of system I see as being necessary.

The technical system would be a document ticketing system to cover ALL documentation.

The system would take inputs from any other system - bugzilla, askubuntu, help.u wiki.u, wordpress, the man page viewer, support ticketing system, launchpad, github, and any other place where documentation exists, questions are asked or ubuntu content exists or is created (yes, this means we would need plugins for major content creation systems).

Tickets would collet a little basic data - url, date, reporter, ubuntu version, other software used (and versions) and a note about what the documentation or problem is.

The ticket is then reviewed by an editor, where the ticket is assigned a team, a support level, a difficulty level, a likelihood level and a severity.

Those tickets are then picked up by various team members (including both paid staff and volunteer staff depending on the team or teams it is assigned to)

Teams are fairly obvious.

Document levels refer to the supported status of a document. Level 1 documents are considered unsupported documents. On the public side, these are very appropriate for brand new volunteer editors and would appear on a site like wiki.ubuntu.com. On the internal side, they may be a shared note for support staff.

When a level one document is ready (or another pressing need for that document comes up), it gets promoted to level 2. At this stage, it is reviewed by a mid level editor, cleaned up and fleshed out. For internal documents, this may be taking a support note and giving a basic methodology of fixing a problem.

Level 2 docs get promoted to level 3, or minimally supported documents. For public documents, these may get promoted to help.ubuntu.com.

Level 3 docs are fully supported documents. They may have a technical team already assigned to them. The public documents are supported by staff, and are updated for every version of ubuntu.

level 4 docs are the official docs (e.g. server guide and desktop guide).

Level 5 docs are for paid subscribers and are fully supported by paid staff.

Docs should have tabs. The official published version, the current working version, and the suggested edits tab.

likelihood and severity are ratings on how common the issue is and how bad it is when it happens. These scores allow for prioritizing documentation issues.

difficulty is a rating of how difficult the editor thinks the job is. 1’s may be simple spelling and grammar errors, where level 5 is a complete rewrite of a major documents. This is used to help assign volunteers and staff appropriately.

Thats a start on a high level system.

1 Like