User:Pavithraes/Sandbox/Technical writer guide

From MediaWiki.org
Jump to navigation Jump to search

Overview[edit]

Effective technical documentation is a product of effective planning, production and presentation. Some useful notes and resources have been included in this page to support technical collaborators through each of these phases.

Technical writing process[edit]

  1. Create a document plan. Clearly define the following:
    • Audience: Who is this information/document intended for? What is their skill level? Who else will read the document? Which community will the readers belong to?
    • Purpose: Why is the topic relevant? What should be the outcome of reading the document?
    • Context : What is the broader scope of the topic? Where will the document be published? How is the environment of the platform? What is the theme/mood of other related documentation on the platform?
    • Document type: What is the best way to communicate the information? Which document genre will suit my purpose, audience and context the best? Refer to technical documentation templates and suggestions.
  2. Create a draft
    • Collect relevant content and record the sources for citations.
    • Structure the content based on the 'document genre' and include transitions wherever necessary.
    • Give the document an appropriate title. Keep the title simple and searchable. Note to use sentence case for the document title and section headings.
    • Follow the language guidelines and write for translation.
  3. Review: Ask the community and non-community members for feedback on the draft. Consider the suggestions and make necessary changes. It is good practice to check for biases and information gaps in this phase. See #Communication.
  4. Publish the document after verifying the final document against the #Checklist.
  5. Maintain the document: Technical documentation is never complete, it requires constant updates and maintenance. Take ownership of the document and revise it regularly.

Content collection[edit]

Documentation users care more about the quality of documentation than the quantity of information, and the quality of documentation directly depends on the quality of content. Here are a few pointers:

  • It is commonly advised to start, and not end with Wikipedia.
  • Going through similar technical documentation of other open-source projects can help understand the type of content needed.
  • Besides websites, books, articles and research papers are good reference materials.
  • Make sure to refer to MediaWiki/Wikitech/etc. pages to avoid content duplication and to collect useful references.
  • Sometimes the related codebase and phabricator tasks are also good places to find recent information.
  • For project specific information, you can communicate with the developers over IRC, mailing lists, Phabricator, Zulip, etc.

Communication[edit]

At a place like MediaWiki, where anyone can edit, effective communication is especially important for sucessful collaborations.

Collaborators interact on the talk pages, Phabricator tasks, sometimes on Gerrit (code-review), mailing-lists and additional group chats like IRC, Zulip, Slack, etc. The following are some points to note while interacting with the Wikimedia community:

  • Follow Wikimedia's Code of conduct strictly.
  • Use simple language and a friendly, yet professional tone at all times.
  • Be mindful of the previous work done on a project and it's documentation.
  • Understand that a new contributor may work on a project in the future and include all necessary remarks and references in the talk page.

Checklist[edit]

A list of items to review your documentation against before publishing.

Common mistakes[edit]

Structure[edit]

  • Failing to include an 'Overview section' on wiki pages.
  • Using title case, instead of sentence case for headers.
  • Inconsistent fonts throughout the document.

Language[edit]

Grammar[edit]

  • Misplaced commas.
  • Incorrect use of its and it's.

Resources[edit]

Technical writing[edit]

Documentation tools[edit]

Documenting APIs[edit]

See also[edit]