diff options
author | Mike Lewis <mlewis@gitlab.com> | 2018-12-31 18:02:34 +0300 |
---|---|---|
committer | Mike Lewis <mlewis@gitlab.com> | 2018-12-31 18:02:34 +0300 |
commit | 1ca583ed74e67c1337bd807d31f5b1e5b0ef9289 (patch) | |
tree | d0f66005454bc59c61e616e11687a31db5de21b8 /doc | |
parent | 66b127a5f476176a85a9e7a50837d110fdd0aa83 (diff) |
Update Content section
Diffstat (limited to 'doc')
-rw-r--r-- | doc/development/documentation/styleguide.md | 29 |
1 files changed, 12 insertions, 17 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 78d129763e7..7e5e6272e54 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -40,27 +40,22 @@ Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class} ## Content -In docs, we share any and all helpful information, processes, and tips for implementing, +These guidelines help toward the goal of having every user's search of documentation +yield a useful result, and ensuring content is helpful and easy to consume. + +- What to include: + - Any and all helpful information, processes, and tips for implementing, using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot) for this information. - -There is no reason to withhold 'risky' steps and store them in another -location; simply include them along with the rest of the docs including all necessary + - 'Risky' or niche problem-solving steps. There is no reason to withhold these or +store them elsewhere; simply include them along with the rest of the docs including all necessary detail, such as specific warnings and caveats about potential ramifications. - -Any content that is relevant to users or admins may be included. You can freely + - Any content types/sources, if relevant to users or admins. You can freely include presentations, videos, etc.; no matter who it was originally written for, -if it is helpful to any of our audiences, we can include it. - -Among other recommended subsections, a `Troubleshooting` section in doc pages is -part of the default [template](structure.md) for a new page, and can freely be -added to any page. - -These guidelines help toward the goal of having every user's search of documentation -yield a useful result, and ensuring content is helpful and easy to consume. - -When working on documentation: - +if it is helpful to any of our audiences, we can include it. If an outside source +that's under copyright, rephrase, or summarize and link out; do not copy and paste. + - Sections like `Use Cases` and `Troubleshooting` can be added to any page where they +apply. See the [structure and template](structure.md) page for more details. - Make sure each markdown file exists in the [correct directory](index.md#documentation-directory-structure), is linked from its higher-level index page, and is linked from other related pages. |