diff options
author | Marcia Ramos <virtua.creative@gmail.com> | 2018-08-16 09:30:04 +0000 |
---|---|---|
committer | Marcia Ramos <virtua.creative@gmail.com> | 2018-08-16 09:30:04 +0000 |
commit | 819f6d9bceda9a618c2983484ccd3ef59f97fdde (patch) | |
tree | ea55f6e86fdfdcccca9c593d5441c9d2c3efd441 /doc/development/documentation/structure.md | |
parent | 0a666b2cb1020df4b8f7b71041b6bd109b49656a (diff) | |
download | gitlab-ce-819f6d9bceda9a618c2983484ccd3ef59f97fdde.tar.gz |
Documentation process at GitLab
Diffstat (limited to 'doc/development/documentation/structure.md')
-rw-r--r-- | doc/development/documentation/structure.md | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md new file mode 100644 index 00000000000..1002836096a --- /dev/null +++ b/doc/development/documentation/structure.md @@ -0,0 +1,149 @@ +--- +description: Learn the how to correctly structure GitLab documentation. +--- + +# Documentation structure + +For consistency throughout the documentation, it's important to maintain the same +structure among the docs. + +Before getting started, read through the following docs: + +- [Contributing to GitLab documentation](index.md#contributing-to-docs) +- [Merge requests for GitLab documentation](index.md#merge-requests-for-gitlab-documentation) +- [Branch naming for docs-only changes](index.md#branch-naming) +- [Documentation directory structure](index.md#documentation-directory-structure) +- [Documentation style guidelines](styleguide.md) +- [Documentation workflow](workflow.md) + +## Documentation blurb + +Every document should include the following content in the following sequence: + +- **Feature name**: defines an intuitive name for the feature that clearly +states what it is and is consistent with any relevant UI text. +- **Feature overview** and description: describe what it is, what it does, and in what context it should be used. +- **Use cases**: describes real use case scenarios for that feature. +- **Requirements**: describes what software and/or configuration is required to be able to +use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial. +For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc. +Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement. +(Another doc page, a third party application's site, etc.) +- **Instructions**: clearly describes the steps to use the feature, leaving no gaps. +- **Troubleshooting** guide (recommended but not required): if you know beforehand what issues +one might have when setting it up, or when something is changed, or on upgrading, it's +important to describe those too. Think of things that may go wrong and include them in the +docs. This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. Answering them beforehand only makes your +document better and more approachable. + +For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs). + +### Feature overview and use cases + +Every major feature (regardless if present in GitLab Community or Enterprise editions) +should present, at the beginning of the document, two main sections: **overview** and +**use cases**. Every GitLab EE-only feature should also contain these sections. + +**Overview**: as the name suggests, the goal here is to provide an overview of the feature. +Describe what is it, what it does, why it is important/cool/nice-to-have, +what problem it solves, and what you can do with this feature that you couldn't +do before. + +**Use cases**: provide at least two, ideally three, use cases for every major feature. +You should answer this question: what can you do with this feature/change? Use cases +are examples of how this feature or change can be used in real life. + +Examples: +- CE and EE: [Issues](../user/project/issues/index.md#use-cases) +- CE and EE: [Merge Requests](../user/project/merge_requests/index.md#overview) +- EE-only: [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html#overview) +- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.md#overview) + +Note that if you don't have anything to add between the doc title (`<h1>`) and +the header `## Overview`, you can omit the header, but keep the content of the +overview there. + +> **Overview** and **use cases** are required to **every** Enterprise Edition feature, +and for every **major** feature present in Community Edition. + +### Discoverability + +Your new document will be discoverable by the user only if: + +- Crosslinked from the higher-level index (e.g., Issue Boards docs +should be linked from Issues; Prometheus docs should be linked from +Monitoring; CI/CD tutorials should be linked from CI/CD examples). + - When referencing other GitLab products and features, link to their +respective docs; when referencing third-party products or technologies, +link out to their external sites, documentation, and resources. +- The headings are clear. E.g., "App testing" is a bad heading, "Testing +an application with GitLab CI/CD" is much better. Think of something +someone will search for and use these keywords in the headings. + +## Documentation template for new docs + +To start a new document, respect the file tree and file name guidelines, +as well as the style guidelines. Use the following template: + +```md +--- +description: "short document description." # Up to ~200 chars long. They will be displayed in Google Search Snippets. +--- + +# Feature Name **[TIER]** (1) + +> [Introduced](link_to_issue_or_mr) in GitLab Tier X.Y (2). + +A short description for the feature (can be the same used in the frontmatter's +`description`). + +## Overview + +To write the feature overview, you should consider answering the following questions: + +- What is it? +- Who is it for? +- What is the context in which it is used and are there any prerequisites/requirements? +- What can the user do with it? (Be sure to consider multiple audiences, like GitLab admin and developer-user.) +- What are the benefits to using it over any alternatives? + +## Use cases + +Describe one to three use cases for that feature. Give real-life examples. + +## Requirements + +State any requirements, if any, for using the feature and/or following along with the tutorial. + +The only assumption that is redundant and doesn't need to be mentioned is having an account +on GitLab. + +## Instructions + +("Instructions" is not necessarily the name of the heading) + +- Write a step-by-step guide, with no gaps between the steps. +- Start with an h2 (`##`), break complex steps into small steps using +subheadings h3 > h4 > h5 > h6. _Never skip the hierarchy level, such +as h2 > h4_, as it will break the TOC and may affect the breadcrumbs. +- Use short and descriptive headings (up to ~50 chars). You can use one +single heading `## How it works` for the instructions when the feature +is simple and the document is short. +- Be clear, concise, and stick to the goal of the doc: explain how to +use that feature. +- Use inclusive language and avoid jargons, as well as uncommon and +fancy words. The docs should be clear and very easy to understand. +- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me"). +- Always provide internal and external reference links. +- Always link the doc from its higher-level index. + +<!-- ## Troubleshooting + +Add a troubleshooting guide when possible/applicable. --> +``` + +Notes: + +- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly +- (2): Apply the correct format for the [GitLab version introducing the feature](styleguide.md#gitlab-versions-and-tiers) |