User:Pavithraes/Sandbox/Technical writer guide

Overview

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

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

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

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

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

• Verify if your document follows MediaWiki's documentation style guidelines:
  • Structural guidelines
  • Language guidelines
• Check your content for any:
  • biases in writing.
  • gaps in the information.
• Make sure your document is easy to translate.
• Check if all the applicable categories are listed.

Common mistakes

Structure

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

Language

• Using long and complex sentences.
• Using unecessary jargons.
• Not using an imperative mood.

Grammar

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

Resources

Technical writing

• What is technical writing
• Technical writing specifications
• Write the docs - Beginner's guide to docs
• Technical style

Documentation tools

• Comparison of automatic documentation generators
• Confluence documentation

Documenting APIs

• Documenting your API
• The ten essestials for good API documentation

See also

• Documentation
• Documentation/Technical documentation prioritization
• Documentation/New technical writers