Saltar al contenido principal

Documentation Working Group

Documentation Working Group is aimed at developing high-quality user and developer documentation. The Documentation Working group is geared towards making sure that all of the important software, tools and projects are well-documented with a standard developer experience defined to help new contributors in getting started with the community.

The Documentation Working Group is specifically used for capability building, bringing onboard new contributors, and helping them to get started, while making sure that the influx of new contributions is not hindered by a lack of good documentation. The next sections of this document describe how the Documentation Working Group is coordinated, and what sort of impact it has in the large and diverse community that makes up moja global.

What is the Documentation Working Group doing?

As the name suggests, the primary goal of the Documentation Working Group is to develop documentation for various projects under the moja global umbrella. However, to better understand how to connect our efforts on documentation, an understanding of how documentation is currently developed at moja global is required.

For every project release, a new Documentation plan is created after the epic list for the release is obtained. The epic list describes the bugs that were fixed, the features that were added, and all the trivial/non-trivial changes that were made that hold importance with respect to users and developers. Based on the epic prioritization and bandwidths, the Documentation Working Group commits to documenting the epic list for the release. The Docs Plan is signed off by all the key stakeholders, which includes contributors, ambassadors, coaches and maintainers.

The general documentation development process is very lucid, yet very intuitive, for our use-case. It includes the following steps:

  1. Research: The documentation research process is an intensive one and we depend on developer inputs while performing the research.

  2. Draft: Based on the prior research done, a draft can be prepared which is then reviewed by the stakeholders before signing it off.

  3. Review: After the release of the final draft, the developers/maintainers review the draft and suggest improvements and provide feedback before it is sent as a Pull Request.

  4. Merge: The documentation is peer reviewed, and after all suggestions are incorporated, the write-up is merged to the official documentation and hosted.

Documentation Planning and Scope of Work

But where do we plan for documentation releases and developing new documentation pieces? The Documentation issues are created on the respective repositories through GitHub Issues, where they are tracked and accounted for by the stakeholders. All the documentation-related issues are labelled as “documentation”. At the end of the day, as a volunteer for the Documentation Working group we work on:

  • Creating user-story based end user documentation that makes complex things easy to understand so that even a first time user can quickly start using our projects.

  • Creating modular content that can be reused/repurposed for different formats and different use cases.

  • Adhering to minimalism practices, logically structuring our content, and endeavoring to make it as findable as possible.

  • Reduce the number of developer/user issues the engineering team needs to deal with on GitHub.

As part of the Documentation Working group, we work asynchronously with the engineering teams to set a clear Release, feature freeze, and code freeze dates, which allows us to set our Documentation freeze and even Release Notes dates.

Remember, docs or it didn’t happen.

What are the different areas we work on?

The Documentation Working Group is not limited to only software documentation, release notes and user/developer documentation. We work on a plethora of things which concerns the overall Content Strategy in place for moja global (under development). As an abstraction, some of our work is concerned with the following:

  • Training Material: Training materials are of utmost importance for new developers and contributors at moja global. It helps them upskill quickly and makes them fit to contribute in a short space of time. moja global publishes its training materials over Moodle learning management system (LMS) which will be expanded over time.

  • Website maintenance: We love to have people with some experience in Web Development to maintain our main website and the community website. The skill set depends on the area of work, but the significant part of the website maintenance concerns itself with updating content, writing blogs and content which can be published centrally.

  • Promotion: The primary reason why documentation itself is so much focussed on is because of its potential to develop the community outreach and for promotion. As part of the Documentation Working group, we work on promotional content for Social media channels that can be utilized to spread the word about moja global and how people can contribute to our initiative.

  • Coordination: moja global contributors put a lot of focus on a documentative approach of communication. Every message written on Slack or the mailing list, if carefully written, can be reused in the future as a resource that can be helpful to new contributors. The coordination effort relies on finding these resources which can be integrated with the documentation and coordinate the forums and mailing lists.

Tools & Technologies

We are yet to decide on the tools and technologies that we will employ for our purpose. However some of them that are most commonly employed are Markdown, Docusaurus, Sphinx, ReadTheDocs, Moodle, GitHub Issues, GitHub Project Board. We also would like to use more efficient project management tools to track our documentation and releases and we are open to suggestions for the same.

How to get involved?

The Documentation Working Group is entirely driven by volunteer efforts but we like to keep track of all the contributors who would like to join. It helps us set proper workflows, processes and contribution pipelines that allows us to track the work being done and set realistic timelines. You can pitch for several documentation-specific domains that you would like to contribute to.

We hold a biweekly meeting every second Tuesday at 4:30 PM (IST) / 7:00 AM (EST) / 9 PM (AEST) / 11 AM GMT. If you would like to get involved, feel free to stop by (or anytime!) to introduce yourself. You can also send a message in the #documentation channel of our Slack.