📑Google season of docs

We are participating in Google Season of Docs 2022!

Application

Ushahidi is participating in Google Season of Docs 2022. We are therefore contracting a technical writer for 20 hours/week between mid May - November 2022. The hourly rate is based on location and experience.

If you have experience documenting APIs and is familiar with the PHP programming language, please apply through filling in this form. Please submit your application before 10th of May 2022, 6pm UTC.

Update the technical documentation for The Ushahidi platform API

About Ushahidi

Ushahidi is a non-profit whose mission is to build and use open source technology to help marginalized groups raise their voices and the organizations that serve them to listen and respond better. In doing so, we build capacity in marginalized communities to leverage technology for social change. We believe that if marginalized people are able to easily communicate to those who aim to serve them via the communication channels they already use about their issues, needs, and eyewitness reports, then those organizations who aim to help them can more effectively and efficiently respond to their immediate and direct needs, while simultaneously bringing global attention to their plight through the aggregation of their voices.

About the project

Problem to solve

The Ushahidi Platform is an open source tool and we have contributors working on our code as well as organisations that wants to extend the tool for their purposes.

For these users, up to date, clear and correct documentation is important. Our current documentation was updated in 2018, since then, a new version of the API is under development and some endpoints are already used in our own web client. Unfortunately, there is no documentation for this version, which this causes confusion for our users, causes delays in their work and requires sending questions and waiting for answers from our support-team. It also means our support team spends time on tasks that could be in the documentation and have less time for helping users with more complicated problems.

This project aims to update and create new documentation for the Ushahidi platform API. The goals are:

• Make it easier to find out what the Ushahidi Platform is capable of and what it can be used for

• Make it easier for a user to figure out if the tool is for their project or not

• Make it easier for users to access help and support without having to wait for a team member to reply

• Encourage innovation that involves using the API

Scope of the project

The scope of the project is to update and create new documentation of the endpoints that are available in version 3 and version 5 of the Ushahidi Platform API. The platform API has more than 100 endpoints. The scope of this work is to complete documentation for all endpoints dealing with posts and surveys and at least 75% of the other endpoints.

For each endpoint there should be:

• Clear descriptions how to use each endpoint:

  • The URL of the endpoint and methods

  • Resource description

  • Parameters needed (header-, path- and query-string parameters)

  • Authorisation

  • Request bodies

• Example requests

• Example responses

Work that is out-of-scope for this project:

• Any other technical documentation, such as setting up the environment locally, deployment, hosting etc.

Measuring success

The goal is to:

• Have 100 % of the endpoints connected to /posts, /surveys and /forms documented.

• Have at least 75% of the other endpoints documented.

• The number of technical support-questions goes down by 30% after new docs are published

Timeline

Period	Task
May	Orientation, getting familiar with The Platform
June	Test existing documentation and identify gaps and documentation that is not clear enough/instructions that are incomplete or not working. Create list of endpoints missing
July-October	Create and update documentation Create example requests and responses
November	Project completion

Budget

Budget item	Amount (USD)	Running total (USD)	Notes
Technical writer	13440	13440	20hr/week for 6 months at 28$/hr (source https://www.salary.com/research/salary/benchmark/technical-writer-i-hourly-wages)
Volunteer stipends	1000	14440	2 mentors
T-shirt and schwag for technical writer	200	14640

Additional information

In 2018 we got funding from Digital Impact Alliance to improve and collect our documentation in one place.

During the project we:

• Collected our docs that was spread out in many places into one home: docs.ushahidi.com

• Added missing documentation for the platform-client, the pattern-library and the API

• Added missing documentation for setting up the developers-environment and deploying to production

• Added missing documentation for QA and design-processes

One of the mentors participating in this project was participating in a large part of the DIAL project and writing a lot of the documentation.

Review processes

We review our documentation via testing it ourselves and we also make sure to learn and improve the documentation from the experiences our interns and contributors have when setting up the platform from scratch. This gives us insights we would not get otherwise, since they are new to the project and see things in a different light than us who are working with it everyday.

Previous participation in Season of Docs, Google Summer of Code or others

Ushahidi has previously participated in Google Summer of Code and Outreachy. Since 2018 we have had at least one intern per year.