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 the mentioned phases.

This is a community help guide. We welcome you to add more helpful references for technical documentarians.

Steps to writing technical documentation

 * 1)  Clearly define the context and purpose of the documentation  to help you focus your ideas in the right direction. The best way to define your purpose is to design a problem statement that your documentation solves. An important part of this step is to outline the topics your documentation should and shouldn't cover.
 * 2)  Understand your audience. Take a moment to think about who your intended readers are, their background, their levels of expertise, etc. This will help you recognize the best format to deliver your content.
 * 3)  Decide on a document genre once your purpose and target audience are clearly defined. There are many different types of documents' that can be used to deliver your content. See technical documentation templates and suggestions.
 * 4)  Collect relevant content for the documentation. This is an elaborate and time-consuming process as content forms the foundation of your documentation. See content collection.
 * 5)  Give the content a rough structure  before creating your first draft. It helps you organize your thoughts and have a clear mind map during the writing phase. It is important to keep the structure flexible. The Documentation/Style guide is a handy reference.
 * 6)  Create your draft using any text editor that you're comfortable with. If you wish to edit on-wiki, you can use the visual editor or the source editor (select Syntax highlighling tab from the top bar for highlighting the wiki markup syntax. Also add hyperlinks, format the text and use templates wherever necessary.
 * 7)  Proofread and review the document against this checklist. 

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.

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.

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.

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.

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