OpenMRS Documentation Guide

Thank you for your interest in the OpenMRS Community! We have created this guide for people who are curious about becoming Technical Writers in our community. This guide gathers the collective wisdom of the Write the Docs community around best practices for creating software documentation. If you find yourself eager to get started, we've also included some practical advice on specific steps you can take right away to start doing documentation work with the OpenMRS community.

 Types of Pages/templates On the OpenMRS Wiki

• Project pages
• Meeting Pages
• Meeting conventions  (all meetings minutes on etherpad, posted on meeting announcement)
• Release Pages ( Sprints are captured in JIRA and links provided on the release page)
• Roadmaps
• Technical documentation 
• Processes like  Roadmap, Release Management and Creating a New Project
     

A beginner’s guide to writing documentation

For Whom to write 

First, you need to ask yourself who you’re writing for in the community. There are a number of consumers who visit our resources 

• Users: (curious, government officials, students, and implementers) these are people who want to use the software and are more concerned with the user experience.
• Developers: (students, professional volunteers etc.) are people who want to contribute back to your code.

Where to I find information on current documentation

A lot of people visit openmrs documentation to try to figure out what exactly the project is all about. Someone will mention it, or they’ll google a phrase randomly. You should explain what your project does and why it exists.  This is were to find openmrs documentation OpenMRS Wiki, OpenMRS website, GitBook and GitHub

A link to your code & issue tracker

People like to browse the code sometimes. They might be interested in filing bugs against the code for issues they’ve found. Make it really easy for people who want to contribute back to the project in any way possible.

Frequently Asked Questions (FAQ)

A lot of people have the same problems. If things happen all the time, you should probably fix your documentation or the code, so that the problems go away. However, there are always questions that get asked about your project, things that can’t be changed, etc. Document those, and keep it up to date.

How to get support

• By creating a poll on talk and tagging in some members 
• Reaching out to members directly through IRC baring in mind the chat tips on this  link https://wiki.openmrs.org/display/IRC/OpenMRS+Chat+Tips
• Joining documentation PM call every Tuesday at 4pm - 5pm EAT

Information for people who want to contribute back

People usually have standards for how they expect things to be done in their projects. You should document these so that if people write code or do software installation, they can do things in the norm of the project.

Installation instructions

Once people figure out they want to use our software, they need to know how to actually get it and make it run. Your installation instructions should be a couple lines for the basic case. A page that gives more information and caveats should be linked from here if necessary. 

Starting off

How to get started

These are the steps to follow when getting started as a Technical writer in openmrs community:

• Create an OpenMRS ID . Your OpenMRS ID defines your username in the OpenMRS community and provides access to community resources, like the wiki, Issues tracker, and the OpenMRS Talk forums.
• Create a new case at OpenMRS Helpdesk stating you’d like to contribute and would like edit access to Wiki and JIRA. Because of spammers, we must require this extra step before you can edit the wiki pages or make any changes to JIRA tickets.
• Join discussions at OpenMRS Talk for more updates and clarification if need arise.
• Then introduce yourself to the community. You can learn more about how to use Talk by reading this introduction and FAQ.
• This where to find openmrs documentation: OpenMRS Wiki, OpenMRS website,GitBook and GitHub 
• Join the documentation forum every Tuesday between 4 – 5pm EAT / 1- 2pm UTC on this link https://www.uberconference.com/openmrs
• Meet other community members through real-time chat in Telegram (telegram.me/openmrs) or IRC (irc.openmrs.org).
• When you complete work on your project , log your time spent on that issue and “Request Review” and your mentor will get you some feedback in short order.
• Avoid staying assigned to issues/project you aren’t actively working on . When you no longer want to work on an issue that you have already assigned to yourself, please remember to un-assign yourself from it such that others can take it up.
• If you have any findings that you feel would be useful to whoever takes it up, please feel free to add a comment.
• Technical writers, please share your experiences (good or bad) on this link. We are always trying to find ways to improve where we can do better and reinforce things we are doing well, so getting input from your perspective is very helpful & appreciated.

Style and format for our documentation

 Openmrs has its own style format which can be accessed on this link https://wiki.openmrs.org/display/~evoeges/Documentation+Style+Guide

What are our expectations around the style of writing?

Should we have a review process before documentation is accepted as final? (e.g. like how we conducted the first round of documentation review at the beginning of the year?)

Contributing To The Documentation

Editing our documentation

This document describes what documentation contributors should follow to ensure consistency throughout all publications. Contributing to the document is an excellent way to get involved, meet the community and to improve on your knowledge! Don’t hesitate to contribute also if English is not your first language!

Overview

The document that is hosted on GitHub.

• Create different branches for changes you make.
• Some external documentation is pulled in, to collect all the documentation in one place.

General Guidelines

Please follow these general guidelines.

• DO NOT commit to master directly. Even for the smallest and most trivial fix.
• ALWAYS open a pull request and ask somebody else to merge your contribution.
• NEVER merge it yourself.
• If you work on a ticket, assign yourself to it.
• Create ‘small’ pull requests, one per each file, these are easier and faster to review, think quality over quantity !

Edit In The Cloud

Head over to the documentation repository.

You can then click the Fork button in the upper-right area of the screen to create a copy of our site in your GitHub account called a fork. Make any changes you want in your fork, and when you are ready to send those changes to be merged, go to the index page for your fork and click New Pull Request to notify the reviewers.

• Fill in the text-box Commit changes describing the changes you made.
• Press the button Commit changes next to it when you are done.
• Head to the green New pull request button (e.g., by navigating to your fork’s root and clicking Pull requests on the right menu-bar.
• Click Send pull request.

This is the recommended way for smaller changes, and for people who are not familiar with Git. Your changes are now queued for review under project’s Pull requests tab on GitHub.You will receive a message when your request has been integrated into the documentation.At that moment, feel free to delete the copy of the documentation you created under your account on GitHub. Next time you contribute, fork again. That way you’ll always have a fresh copy of the documentation to work on.

Before You Make A Pull Request

• Before you commit your changes, it’s a good idea to run a spell check.
• Make sure that all links you put in are valid.
• Check that you are using valid restructured text.

Pull Request Checklist

Making a good pull request makes life easier for everybody:

• The title and description of a pull request should be descriptive and need to reflect the changes.

We use a template which creates a default form for pull requests

Editing the Docs using Git

This is the recommended method of editing the documentation for advanced users. If you are already a member of openmrs organization on GitHub, create a branch in the documentation repository. If you are not a member you can also create a fork of the documentation repository into your own repository.

• Edit the file(s) which you want to update.
• Check that you do not have any syntax errors or typos
• Commit your changes and create and open a pull request.

 Basic steps to editing any pages

• Anyone who has an openmrs account and is logged in can make an edit to a wiki page.
• When you’re on the page you want to edit, hit the Page Tools drop-down menu below the Table of Contents button.
• Select Edit button below the wiki page name. Don't worry, any changes you make can be undone or "rolled back".  
• Any changes you make will be saved when you hit the blue SAVE button in the upper right corner of the edit window. 

Important Links

Openmrs website:  https://openmrs.org/

Openmrs talk: https://talk.openmrs.org/

Openmrs wiki:https://wiki.openmrs.org/

Chart tips: https://wiki.openmrs.org/display/IRC/OpenMRS+Chat+Tips