Mattermost project
Stay organized with collections
Save and categorize content based on your preferences.
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:
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.
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
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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-11-08 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-08 UTC."],[[["\u003cp\u003eThe project aims to review and refine the in-product text of the Mattermost open-source platform for improved user experience.\u003c/p\u003e\n"],["\u003cp\u003eA style guide will be created for UI text elements like buttons, labels, and error messages to ensure consistency and clarity.\u003c/p\u003e\n"],["\u003cp\u003eUser-facing strings will be prioritized for review and refinement based on the established style guide.\u003c/p\u003e\n"],["\u003cp\u003eThe project is estimated to be completed within a standard 3-month timeframe, with potential extension depending on the volume of strings.\u003c/p\u003e\n"],["\u003cp\u003eCategorization of system and user-facing strings will happen concurrently with the style guide development.\u003c/p\u003e\n"]]],["The core actions of the project are to classify strings in Mattermost's web app, differentiating between system and user-facing strings. A style guide will be created for user-facing strings, addressing capitalization, length, word usage, and token usage across UI elements. Based on this guide, the technical writer will review and refine the user-facing text, submitting pull requests on GitHub. The writer will start by focusing on a standard 3-month timeline but would consider extending.\n"],null,["# Mattermost project\n\nThis page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\nProject summary\n---------------\n\nOpen source organization:\n: Mattermost\n\nTechnical writer:\n: @anindita_basu\n\nProject name:\n: Review and Refine In-Product Text\n\nProject length:\n: Long running (5 months)\n\nProject description\n-------------------\n\nI joined the Slack channel and shot off some questions to Eric. Based \n\non his response (thank you, Eric!), I propose to approach this project in \n\nthe following manner:\n\n1. Classify the strings\n\n I will begin with identifying which of the strings (\u003chttps://github.com/mattermost/mattermost-webapp/blob/master/i18n/en.json\u003e) are system console ones, and which ones are user-facing. I propose to take up the user-facing strings for review at first.\n2. Create a style guide for the strings\n\n 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 \u003chttps://github.com/AninditaBasu/AninditaBasu.github.io/blob/master/gsod/Capture7.PNG\u003e). Also, I'd like to create some guidance around the use of tokens (placeholders) in strings, especially composite strings.\n\n 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.\n\n 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\n3. Review and refine the text\n\n Based on the style guide created at #2, I will edit the strings and create pull requests at GitHub.\n\n=============\n\nDuration\n\nI 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.\n\nSince 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."]]
