User:Pavithraes/Sandbox/Technical writer guide

Overview
Effective technical documentation is a product of effective planning, production and presentation.

Steps to writing technical documentation

 * 1)  Clearly define the context and purpose of the documentation.  This will help focus your ideas in the right direction. The best way to define your purpose is to have a secific 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 level of expertise, etc. This will help you recognize the best way to deliver your content.
 * 3)  Decide on a document genre once the purpose and audience are clear. See templates and suggestion.
 * 4)  Collect relevant content for the document. This is an elaborate and time consuming step. The content forms the foundation of your documentation. See #content_collection_strategy for more information.
 * 5)  Give the content a rough structure  before creating your first draft. It helps you organize your thoughts and have a clear mental map during the writing phase. It is important to keep the structure flexible. Refer to the Styel, guide.
 * 6)  Create your draft using any text editor you're comfortable with. Add hyperlinks, format the text, etc wherever necesasary.
 * 7)  Proofread and review the document agains the 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.


 * Start, do'nt end with Wikipedia.
 * Besides websites, books, articles and research papers are good reference materials.
 * Going through similar technical documentation of other open source projects can help understand the type of content needed.
 * Make sure to refer to mediawiki/wikitecth/etc. pages to aviod content duplication and to collect useful references.
 * Sometimes the codebase and phabricator tasks are also good places to find information.

Checklist

 * Check for structure consistency - style guide
 * Language and tone - style guide
 * Check for any bias. Ask another person to review the doc if needed.
 * Information gap
 * Make sure the document is easy to translate.

Communcation
An open source community depends on it's voulenteer contributors and effective communication becomes important for colaborations.At a place like MediaWiki, where anyone can edit, communication is especially important. In Wikimedia, communiaction happens in the talk pages, phabrictaor tasks, sometimes on gerrit(code-review) and additional group chats like IRc, Zulip, Slack, etc.

Points to note:
 * 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 the necessary remarks and references in the doc/talk-page.
 * Use simple language and a friendly, professional tone at all times.
 * Follow the Code_of_conduct strictly.