Mattermost project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
Mattermost
Technical writer:
@anindita_basu
Project name:
Review and Refine In-Product Text
Project length:
Long running (5 months)

Project description

I joined the Slack channel and shot off some questions to Eric. Based
on his response (thank you, Eric!), I propose to approach this project in
the following manner:

  1. Classify the strings

    I will begin with identifying which of the strings (https://github.com/mattermost/mattermost-webapp/blob/master/i18n/en.json) are system console ones, and which ones are user-facing. I propose to take up the user-facing strings for review at first.

  2. Create a style guide for the strings

    I'd like to define the style for capitalization, length, and word usage for strings used in menu items, action buttons, labels, headings, tooltips, errors, warnings, validations, notifications, and confirmations (see an example styleguide screenshot at https://github.com/AninditaBasu/AninditaBasu.github.io/blob/master/gsod/Capture7.PNG). Also, I'd like to create some guidance around the use of tokens (placeholders) in strings, especially composite strings.

    I aim to keep this guidance to one page of an A4-sized sheet, shorter if possible. Intention being, developers who actually write these strings should find the guidance quick and easy to use, plus, when followed, UI text will show consistency across all screens.

    I propose to do this for two reasons: (a) so that there is consistency in the text matter in terms of grammar and style (b) so that even after GSoD ends, there is a set of instructions that anyone can quickly refer to when they write UI text

  3. Review and refine the text

    Based on the style guide created at #2, I will edit the strings and create pull requests at GitHub.

=============

Duration

I don’t yet know how many of the strings are user-facing strings (which is what I propose to take up for review in this project). I estimate that creating the style guide would take about 3 weeks (from draft to approval), and this work can be done simultaneously with categorizing strings as system strings or user facing. I propose to start with the assumption that project will be a standard-length project (3 months), where I take up only so many strings for review as can be possible within this time frame.

Since I am already employed full time, I would be able to work only part of the day on this project. I am open to the possibility of a longer-duration project if you think my reduced working hours will need it.