Documentation/Maturity model for MediaWiki technical documentation

Overview
This page contains a tentative outline, research and citations for a maturity model for the MediaWiki / Wikimedia technical documentation organization and content. The maturity model is intended to guide assessments about the quality of the existing organizational structure, processes for producing technical documentation and assessing the quality of technical documentation content on MediaWiki and across Wikimedia projects. and help set standards for planning future technical documentation on MediaWiki / WikiMedia 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, specific to technical documentation and communication.


 * 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 sets. 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 scope and scale of existing technical documentation, future needs for technical documentation, or overall quality of content collections. No clear understanding of users or mechanisms for user feedback.
 * 2) Rudimentary: (Needs improvement): Rudimentary standards and processes are being implemented under the guidance of a technical writing/communication professional. Style guides and standards are introduced. Formal processes for managing technical documentation are discussed with attempts at implementation. Early formal processes may include, quality assurance, peer review, copy and developmental editing. However, implementation of processes is not prioritized. Support or resources (time, money, staff) may not be committed. Processes still lack consistency in implementation.
 * 3) Organized and repeatable: (Baseline) Under strong leadership, staff and community agree on uniform processes and are committed to following them. Uniform tools, standards and templates are used. Audience / user needs take priority and inform technical documentation content and organization. Documentation projects are identified by priority and scoped; planning and quality assurance are recognized as key elements to their success. Qualified technical writers/communicators guide this process. At this stage, staff and volunteers may recognize technical content collections in need of redesign and revision. User research is identified as essential to successful quality technical documentation. Technical writers/communicators are working across teams in the organization to surface shared needs, establish benchmarks and identify projects.
 * 4) Managed and sustainable: (Superior) This organization is well-managed and has made a strong commitment to follow through on practices and practices outlined in level three. These process and practices (and with them the quality of technical documentation) will not suffer from changes to management or overturning staff or volunteers. Planning and training would continue. More specialized staff members are hired with a focus on specific aspects of technical writing / communication: document managers, writers, designers, user researchers, etc. An increased focus on user experience takes place at this level. The organization is committed to understanding its users needs and implementing strategies for improvements to technical documentation that best suit these needs. The organization focuses on ways to widen the scope of its technical documentation and training and engage new audiences.
 * 5) Optimizing: (Superior) A self-actualized organization with the maturity to evaluate its own established practices with quality and innovation in mind, an agile organization that can respond to the needs of users and technical collaborators swiftly, as they arise. An organization that seeks improvement and alignment with the strategic direction of the larger organization. Staff members are experienced and knowledgeable; they collaborate effectively with the community and seek to understand the needs of users. They encourage and guide volunteer contributions and work to build sustainable relationships and partnerships with community members who have technical writing / communication skill sets or who wish to grow their skill sets in the context of the movement. This organization looks to similar organizations to evaluate its practices and standards. This organization seeks to be a standard barer and example of excellence within the context of similar organizations.

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/