End-user docs repo – workflows and settings

As you may know, the Documentation team is starting a collaboration with other teams, mainly Polyglots, in translating complete end-user documentation (HelpHub). This documentation and its many translations will have a new place to live: GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ repository WordPress/documentation-end-user.

Before we start translating, we must move all existing docs to the repo. After that is done, all translations, as well as creating new documentation in English and updating the existing one, will happen in that same repository.

This means a lot of new contributors, new contributor roles, different workflows, and different processes… Rather than letting the mess dictate our repo settings and workflows, let’s try to use our experience with Issue Tracker and predict possible problems and needs.

For this purpose, a new GitHub project is created: End-user docs repo – workflows and settings.

As a starting point, let’s identify different user roles contributing to the end-user docs repo and what would make their contributions easier and more streamlined.

All the issues are created as user stories and are only concerned with a single problem.

At this point, there are the following settings in the project. These might be incomplete and/or wrong, which we will know in time.

Persona

• First-time contributor
• Experienced contributor
• Repo maintainer
• Issues coordinator
• First-time reviewer
• Experienced reviewer
• Translator
• Translation editor
• Any contributor

The life cycle of an issue

• Creating issue
• Updating screenshots
• Creating new documentation
• Reviewing issue
• Managing issue
• Working on issue

Type of workflow

• Automation
• Manual
• Template (issue and pull request)

The end result of this effort should give us the idea of the following:

• How the issue/pull request is named – template
• What is the structure of the issue/pull request
• The list of labels with descriptions and explanations of when to use them
• Automated tasks
• The life cycle of the issue/pull request
• Well-defined user roles and their responsibilities

Feel free to start adding new stories and keep in mind to focus on a single problem per issue.