Documentation/Maturity model for MediaWiki technical documentation

Overview
This page contains a tentative outline, research and citations for a maturity model for MediaWiki technical documentation. The maturity model is intended to guide assessments about the quality of existing technical documentation and help set standards for planning future technical documentation on MediaWiki projects.

This is a current Q3 (Jan/Feb/March 2019) for the Wikimedia Developer Advocacy team.

https://phabricator.wikimedia.org/T212003

Maturity models structure
From Maturity model structure


 * Maturity Levels: a 5-level process maturity continuum - where the uppermost (5th) level is a notional ideal state where processes would be systematically managed by a combination of process optimization and continuous process improvement.
 * Key Process Areas: a Key Process Area identifies a cluster of related activities that, when performed together, achieve a set of goals considered important.
 * Goals: the goals of a key process area summarize the states that must exist for that key process area to have been implemented in an effective and lasting way. The extent to which the goals have been accomplished is an indicator of how much capability the organization has established at that maturity level. The goals signify the scope, boundaries, and intent of each key process area.
 * Common Features: common features include practices that implement and institutionalize a key process area. There are five types of common features: commitment to perform, ability to perform, activities performed, measurement and analysis, and verifying implementation.
 * Key Practices: The key practices describe the elements of infrastructure and practice that contribute most effectively to the implementation and institutionalization of the area.

Capability maturity model levels
There are five levels defined along the continuum of the model and, according to the SEI: "Predictability, effectiveness, and control of an organization's software processes are believed to improve as the organization moves up these five levels. While not rigorous, the empirical evidence to date supports this belief."


 * 1) Initial (chaotic, ad hoc, individual heroics) - the starting point for use of a new or undocumented repeat process.
 * 2) Repeatable - the process is at least documented sufficiently such that repeating the same steps may be attempted.
 * 3) Defined - the process is defined/confirmed as a standard business process
 * 4) Capable - the process is quantitatively managed in accordance with agreed-upon metrics.
 * 5) Efficient - process management includes deliberate process optimization/improvement.

Information process maturity model levels
The information process maturity model speaks to how information is produced within the organization. Descriptions here are based on current Mediawiki / Wikimedia organizational structure and resources.


 * 1) Ad Hoc: (Needs Improvement): Characterized by lack of uniform practices. Lone technical writers/communicators managed by non-technical writers/communicators; volunteer technical writers/communicators with varying skill levels. Processes are unique to individual technical writers/communicators, rather than standard, agreed upon across the organization or community. Lack of formal method for prioritizing projects. No clear understanding of users or mechanisms for user feedback.
 * 2) Rudimentary: (Needs improvement)
 * 3) Organized and repeatable: (Baseline)
 * 4) Managed and sustainable: (Superior)
 * 5) Optimizing: (Superior)

At the organizational level:

 * Does the organization support its staff and the community, within the reporting structure and through concentrated efforts to promote efforts to produce and maintain high quality, current technical documentation to technical collaborators? Are there adequate resources (people and funding)? Is there support from the leadership team?
 * Is there an established planning process to for MediaWiki technical documentation, to ensure proper coverage of timely, quality technical documentation, which meets the needs of the intended audience?
 * Is there a system for peer reviewing and editing technical documentation to ensure quality and accuracy?
 * Does the organization have the ability to estimate the time or cost (in staff and volunteer hours) of specific technical documentation projects? Is the organization able to effectively judge whether there is value in concentrating efforts on specific technical content or if resources would be more effectively directed elsewhere?
 * Is there appropriate staffing to undertake technical documentation projects that produce quality content? Are there sufficient resources and support for volunteers in the community who wish to work on these projects?
 * Does the organization actively promote activities (training, write-a-thons/hack-a-thons, conference attendance, community outreach) to demonstrate interest and support for technical documentation efforts?
 * Does the organization actively support efforts to understand audience/user needs in order to ensure technical documentation is appropriate and usable?
 * Are technical communicators and writers collaborating to improve quality and consistency of technical documentation across the organizations projects?

What does mature technical documentation look like?
Tips for writing in technical documentation genres

Citations, resources, readings

 * J. Hackos, Managing Your Documentation Projects. New York: John Wiley & Sons, 1993
 * J. Hackos, Information Process Maturity Model, 017 IEEE International Professional Communication Conference (ProComm), 2017
 * S. Huang, S. Tilley, Towards a documentation maturity model, SIGDOC '03 Proceedings of the 21st annual international conference on Documentation, 2003
 * https://en.wikipedia.org/wiki/Maturity_model
 * https://en.wikipedia.org/wiki/Capability_Maturity_Model
 * Maturity Models 101 - Carnegie Mellon SEI:
 * Measurement and Analysis in Capability Maturity Model Integration Models and Software Process Improvement
 * https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=11965
 * https://opensource.com/open-organization/17/10/readme-maturity-model
 * http://www.contentstrategyinc.com/understanding-content-maturity-model/