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
Helpfully 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"

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"
 * 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"
 * 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"

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"
 * Split long pages

Content relevance and age

 * "remove documentation that it’s not needed anymore"

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."

Connect code and docs

 * Ideas like: 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.
 * Ideas like: 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.

Be transparent

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