Mifos Documentation Contributor Onboarding Guide

Welcome to the Mifos documentation team! This guide is your starting point for helping us improve the project's most critical asset: its knowledge.

As a technical expert, your perspective is invaluable. You don't need to be a professional writer to contribute; we value accuracy and clarity over perfect grammar. Every improvement, from a typo fix to a new guide, has a direct impact on the ability of users worldwide to leverage the Mifos platform.  

This document will walk you through everything you need to know to get started.

Part 1: Your First Steps (5 Minutes)

Let's get you set up for success. This is a quick checklist to ensure you're connected to the community and have the right tools.

• 1. Join Our Main Communication Channels

  • Slack: The #wg-documentation channel is our primary hub for real-time discussions, quick questions, and collaboration. It's the best way to connect with the team.

    • Slack Invite Link: https://bit.ly/mifos-slack-space.  

  • Mailing Lists: For important announcements and deeper technical discussions, make sure you're subscribed to the relevant mailing lists.

    • Fineract Developer List (Technical): Send a blank email to dev-subscribe@fineract.apache.org.  

    • Mifos Developer List (Technical): Sign up via the SourceForge link.  

• 2. Introduce Yourself

  • After joining Slack, pop into the #wg-documentation channel and say hello! Let us know who you are, what your role is, and what areas you're interested in. This helps us connect you with the right people.  

• 3. Check Your Tools

  • Ensure you have Git installed on your machine. You can check by running git --version in your terminal. (This is only needed for the Docs-as-Code workflow in Part 4).  

  • You'll need your Text Editor of choice (e.g., VS Code, Sublime Text, etc.).

  • You'll need a GitHub Account to create pull requests.

Part 2: How You Can Contribute (Choose Your Path!)

Contributing doesn't always mean writing a document from scratch. There are many ways to make an impact, regardless of your comfort level with writing. This guide outlines two primary paths: contributing directly in Confluence/Google Docs (Part 3) and contributing via code repositories (Part 4).

Part 3: Contributing Without Code (Confluence & Google Docs)

Not all our documentation lives in code repositories. A significant amount of valuable content, including user manuals, technical specifications, and training materials, is hosted on platforms like Confluence and Google Docs. This is the perfect place for non-writers to contribute using familiar, user-friendly editors.  

Your expertise is crucial here, as many of these documents need to be reviewed for accuracy, refreshed with up-to-date information, or better structured.  

The Non-Code Contribution Workflow

This workflow is centered around our Jira Service Desk and Google Drive. Each Jira ticket contains specific Acceptance Criteria (ACs) that you must follow.

1. Find and Claim a Task on the Jira Documentation Board:

   • All documentation tasks, including those for Confluence and Google Docs, are tracked on our Jira Service Desk board.

   • Board URL:(https://mifosforge.jira.com/jira/servicedesk/projects/DOC/boards/58) if you don’t have access reach out on #wg-documentation and we will get you sorted.

   • Look for tickets with summaries like "Needs a refresh," "Update content," or "Review for accuracy." These are excellent starting points.

   • Claim the task by leaving a comment like, "I would like to work on this." A maintainer will then assign the ticket to you.

2. Check the Documentation Database:

   • The first step in the ACs is to check if the document already exists.

   • Review the Documentation Database:(https://drive.google.com/drive/folders/1CwqgpEzqErgkGgvvkRZAyKxmA7yx04l6?usp=share_link )

   • If the document exists, proceed to review it. If not, you will create a new one.

3. Review or Create the Document:

   • If the document exists, review it against the following criteria from the ACs:

     • Is it technically accurate and up-to-date?

     • Does it use the latest templates? ((https://drive.google.com/drive/folders/1pV1K7zdWVg0PxAMfFTiOgp7RPxx-CTXt?usp=share_link ))

     • Does it comply with the Style Guide? ((https://docs.google.com/document/d/132CI4dp1PFQJGDABb2D5YOWFWoxivT7mP7KU405fODY/edit?usp=share_link ))

     • Does it comply with the Governance Guide? (Governance Guide Link)

   • If you are creating a new document, start with the correct template and follow the style and governance guides.

   • Store all your work (new drafts or edited versions) in the Working Documentation Drafts Folder: ((https://drive.google.com/drive/folders/1K8ciYzEHvIwCFu8njqKP75y_7aRMgXRJ?usp=share_link )).

4. Submit for Final Review:

   • When your draft is complete and ready for a final review, move the document from the "Working Drafts" folder to the Ready for Review Folder: ((https://drive.google.com/drive/folders/1hmS1OtaQDkInvl7vNKdUhjE12w6OlFZ_?usp=share_link )).

5. Create a Review Ticket in Jira:

   • To formally request the review, you must create a new ticket on the Jira Service Desk.

   • Use the official template for creating review tickets: ((https://docs.google.com/document/d/1hXUxjpU-d1Pju3muctjP24kPmTMe-cHlzNUuZK6Jdsk/edit?usp=sharing )). This ticket will also be used to manage translation if needed.

6. Update the Documentation Database:

   • The final step is to go back to the Documentation Database and update the status of the document you worked on to reflect that it is now "In Review."

Part 4: The Docs-as-Code Workflow (Git & GitHub)

This is the step-by-step process for contributing to documentation that is managed like code. We use Jira for tracking documentation work related to the backend platform (Apache Fineract) and GitHub Issues for the web/mobile apps.  

Step 1: Find and Claim a Task in Jira

All code-related documentation work is tracked in Jira to ensure transparency and prevent duplicate work.  

1. Browse the Jira Board: Visit https://mifosforge.jira.com to find available tasks.  

2. Look for the Right Labels: To start, look for tickets with labels type:documentation and good-first-issue or Introductory. These labels signify tasks suitable for beginners.  

3. Assign Yourself to the Ticket:

   • Open the Jira ticket you want to work on.

   • Leave a comment like, "I'd like to work on the documentation for this ticket."

   • A maintainer will then officially assign the ticket to you. Important: Do not start work until the ticket is assigned to you to avoid duplicated effort.  

Step 2: The Git Process (Fork, Branch, Commit, Push)

Once you're assigned a ticket, it's time to make your changes. We follow a standard GitHub workflow.  

1. Fork & Clone the Repository:

   • Fork the relevant repository (e.g., apache/fineract or openMF/web-app ) to your GitHub account.

   • Clone your fork to your local machine: git clone <YOUR_FORK_URL>

2. Create a New Branch:

   • Always create a new branch for each task. This keeps your work isolated.

   • Use a descriptive name that includes the Jira ticket ID (e.g., FINERACT-123).

   Bash
   git checkout -b doc/FINERACT-123-update-api-guide

3. Make Your Changes:

   • Edit existing files or create new ones as needed to complete the task.

   • Use our Documentation Templates where applicable.

4. Commit & Push Your Changes:

   • Save your work with a clear commit message that references the Jira ticket. This automatically links your work back to Jira.  

   Bash
   git add. git commit -m "docs(FINERACT-123): Update installation guide" git push origin doc/FINERACT-123-update-api-guide

Step 3: Open a Pull Request (PR) for Review

A Pull Request (PR) is how you submit your changes for the team to review.  

1. Go to your fork on GitHub. You will see a prompt to create a Pull Request from the branch you just pushed.

2. Click the button and fill out the PR template. Be sure to link to the relevant Jira ticket in the description.

3. Submit the PR. The team will be automatically notified to review it.

Step 4: The Review and Merge Process

1. Two-Stage Review:

   • Technical Review: A developer will check the technical accuracy of your changes.

   • Style Review: A technical writer will check for clarity, consistency, and adherence to our style guide.

2. Collaboration: Reviewers may leave comments with suggestions or change requests. Please respond to this feedback promptly. It's a collaborative process!  

3. Merge: Once your PR is approved, a maintainer will merge it. Congratulations, your contribution is now part of the official documentation!

Step 5: Clean Up (Best Practice)

After your PR is merged, it's good practice to clean up your branches to keep the repository tidy.  

1. Delete the branch on GitHub (there is usually a button for this on the PR page after the merge).

2. Delete your local branch:

   Bash
   git checkout main git pull upstream main git branch -d doc/FINERACT-123-update-api-guide

Part 5: Style Guide & Templates

To maintain consistency, we have some simple guidelines and templates to help you.

Quick Style Guide

Documentation Templates

Don't start from a blank page! We have created templates in Confluence for the most common document types. Simply copy the content from the relevant template to get started.

• (link-to-your-confluence-template-for-how-to-guide)

• (link-to-your-confluence-template-for-api-reference)

• (link-to-your-confluence-template-for-conceptual-guide)

Note: Best practices from The Good Docs Project and Mozilla Developer Network heavily influence the idea for these templates.

Part 6: Getting Help & Staying Connected

You are not alone! Our community is here to help.

Communication Matrix

Use this table to know where to ask your questions.  

"Doc Buddy" Program & Office Hours

• Doc Buddy: Feeling a bit lost? We can pair you with an experienced contributor who can be your go-to contact for the first few weeks.  

• Office Hours: We hold bi-weekly video call sessions where you can ask questions directly and get real-time help. Announcements will be posted in the #documentation Slack channel.  

FAQ (Frequently Asked Questions)

• Q: What if I'm not a good writer?

  • A: No problem! Our top priority is technical accuracy. Our team will help polish the grammar and style. Your contribution as a subject matter expert is what matters most.  

• Q: What should I do if I get stuck?

  • A: Don't hesitate! Ask in the #documentation Slack channel. There are no stupid questions, and it's likely someone else has the same question.  

• Q: How long does the review process take?

  • A: We aim to provide initial feedback within 2-3 business days. Times can vary depending on the complexity of the PR.  

• Q: What do I do if I have a merge conflict?

  • A: Don't panic! This is a normal part of development. The short guide is to pull the latest changes from the target branch into your branch, resolve them locally, and then push again.

    Bash
    # From within your branch git pull upstream main # or 'develop' depending on the repository # Open the conflicted files and resolve them manually git add. git commit -m "Resolved merge conflict" git push

    If you're still struggling, ask for help in Slack.