Improve doc contribution steps
Issue Description
We have the following page about contributing to docs: https://docs.gitlab.com/ee/development/documentation/index.html
Our handbook page also has a many TW workflows documented, but these are workflows that describe how we work with engineering and product: https://handbook.gitlab.com/handbook/product/ux/technical-writing/workflow/
We don't have a clear landing page or starting point for all contributors. This page should make it easy for anyone, whether they are a community contributor or team member, to know where to get started if they want to update the docs.
Proposal
Updates for this page:
-
Create an issue template for GitLab team members. (Add template for contributing to docs (!233 - merged)) -
Link to the issue template from the page. Make it clear that this template is useful for GitLab team members who plan to update docs regularly. -
Move issue information further down the page (put the task first). -
Make the fork requirements clearer. Make it clear that community contributors need a fork, and include steps for community fork. -
Make it clear that this is for docs contributions. Link out to code contribution pages for folks who want to contribute code? -
Review location of Branch naming and Backport sections. Should they be on this page? -
Update or change existing steps to present the easiest route for community contributors to get started. See Workflows below for possible options.
Workflows
There are various ways that community contributors can update the docs. The different flows to consider are:
- Fork: community fork, own fork.
- Accessing the doc content: navigate to
/doc
in project in UI, click Edit in WebIDE directly from doc page, click View page source directly from page, clone project locally. - Editor: Web Editor, WebIDE, local editor of your choice.
Not all these workflows are interchangeable. There are too many options to document separately. Therefore, propose that we choose one workflow, and document that for users. For the alternative workflows, we can mention them further down the page and link out if needed.
Options
Option 1: Use the community fork. This is the method recommended in our code contribution tutorial. Disadvantage is that you first have to go to the community fork project and work from there. You cannot update a doc page directly from docs.gitlab.com using the community fork (as far as I know - maybe test or check with engineering).
Option 2: Edit a doc page directly from docs.gitlab.com. This might be an easier option for contributors than trying to find the correct page by navigating to the docs directory. The disadvantage is that contributors then have to work from their own fork. This could be fine for a one-off edit, but for contributors who plan to make multiple edits, it places the burden of keeping their fork updated on them.
For both options, also consider whether to use the Web Editor or WebIDE.
- Web editor: easy to use, ideal for a small edit to one page.
- WebIDE: Better for updating multiple pages. But also easy enough to use for one page?