User:TBurmeister (WMF)/Sandbox/Assessment

Ideas and examples of collection assessment criteria and topics, gathered from analysis of the resources listed in https://phabricator.wikimedia.org/T313037.

Ambiguous industry-standard criteria

Note: I am calling these criteria "ambiguous" because there's no consistent and reliable way to assess whether a doc or set of docs meets these criteria. They are important, but too theoretical to use as a tactical checklist.

Mentioned by Xephyr826 in https://phabricator.wikimedia.org/T149372#2948314:

"In the tech writing field, many people have attempted to answer the question of what makes good documentation. One of my favorite descriptions is the seven C's. Good documentation should contain seven properties:

• Clarity - easy to understand
• Coherence - easy to navigate
• Completeness - no missing information
• Concision - no extraneous information
• Consistency - uses the same terms and concepts throughout
• Correctness - tested and verified
• Credibility - Professional, no typos or grammar errors"

Summarized by User:Zakgreant in MediaWiki_Technical_Documentation_Plan:

• Easy-to-read – the documentation should be easy for the primary audience to skim, read and understand.
• Accurate – the documentation should accurately reflect how the software is intended to work and how it is known to work.
• Practical – the documentation should focus on helping the primary audience effectively solve real problems.
• Complete – the documentation should describe as much of the software as possible and should clearly indicate when something is not documented.
• Inclusive – the documentation may be the first point of contact that a person has with the MediaWiki community and should be accessible, friendly and welcoming.
• Consistent – the documentation should save everyone time and effort by being consistent and predictable.

Criteria for content within a collection

Types of information / doc types

For collections focused on a tool, extension, or software component:

• Quick start guides
  • "with sample projects such as TODO apps. Should be able to clone the project from GitHub."
  • "get started quickly"
  • GoodDocsProject Quick Start template
• Tutorials:
  • "animated form of learning that aids imaging things. Help to understand how the flow works."
  • "High level tutorials (show relevant documentation for problem solving)"
  • "need more task-oriented docs, good prerequisites and audience definitions for each doc, links to more in-depth docs if available."
  • "learn to do something specific"
  • "4 (general) types of software documentation (tutorial, how-to, explanation, reference) -- https://www.divio.com/en/blog/documentation/ -- I like the distinction between tutorial (learning) and how-to (goal) there too. Most of what we currently have qualifies as "reference" or "how to." Our biggest gap is probably "walkthrough."
  • "Documentation is not new user-friendly, it needs to have more guidelines or tutorials, and make the onboarding process easier for newcomers"
  • GoodDocsProject Tutorial template
  • "How To articles are often confused with tutorials. How To articles are problem-oriented, while tutorials are learning-oriented."
• README (mixed opinions about whether these should only redirect to on-wiki pages):
  • "a library would have: readme, clear purpose, staffed"
  • "basic 'how to run the code…' doc in github README"
  • "Github readmes and Google Docs to be get rid of as far as we can, READMEs should link to stuff on mw.org."
  • According to Write the Docs, a README should cover:
    • What problem your project solves
    • A small code example
    • A link to your code & issue tracker (if open source)
    • Frequently Asked Questions (FAQ)
    • How to get support
    • Information for people who want to contribute back
    • Installation instructions
    • Your project’s license
• Contact info: to get in touch with experts, ambassadors, mentors, or any human who can help in the topic area.
• Connection to code: link to relevant repos from on-wiki docs (see more in "Findability" section below)
• Overviews
  • "Background and context, along with how the project works"
  • GoodDocsProject explanation template

Content formats

• Beginners - Live learnings, video + picture format. "I want to learn through memes."
• Visual learning experience. "MediaWiki has documentation, but reading huge pages is not fun. Videos / Visual learning is useful to get information quickly."
• "Make Youtube videos"

Content relevance and age

• "remove documentation that it’s not needed anymore"
• User:Zakgreant at some point created "MediaWiki History Sparklines – A Greasemonkey extension for Firefox that uses jQuery, jQuery Sparklines and the MediaWiki API to display sparklines (small graphs) of recent changes to MediaWiki pages. Useful to quickly see if a page is out-of-date or note. Screenshots, source, feature requests and more at http://userscripts.org/scripts/show/79234" (seems dead)

Criteria for findability and organization

Group related content, but also limit lists of links

• All documentation in a given collection should link back to a central portal or landing page
• Creating on-wiki landing pages that link to off-wiki docs.

• "we put too many things in giant list form with too little differentiation."
• "One Topic per Page – Each page should be focused on a particular topic (even if that topic is providing an overview of a variety of related subjects). Where possible, we want to make it clear that there is one place to put, find and update documentation on a given topic. Disambiguate – we should adopt a Wikipedia-like approach of using simple titles for pages and then disambiguating as needed. This allows users to browse the documentation in a very natural fashion and quickly move between related concepts with similar names."

Connect code and docs

• This topic area can cover a huge range of ideas, from including links to repos in a infobox template on-wiki, to continuous integration that looks for the patch ID in an edit summary, publishing wiki docs with an “open patch” label that can be removed once the patch is merged.
• Key takeaway: pick a consistent strategy that's easy to use and can be applied as universally as possible. Then, implement it to create connections between docs that live in non-wiki repos and docs that cover the same topic on-wiki.

Be transparent

• Access to documents should NOT be restricted for viewing by target users (aka remove or update permissions as necessary).