diff options
author | Mike Lewis <mlewis@gitlab.com> | 2019-04-08 02:58:31 +0000 |
---|---|---|
committer | Mike Lewis <mlewis@gitlab.com> | 2019-04-08 02:58:31 +0000 |
commit | 7d59593bf65308f680df40d442e88373a26b3626 (patch) | |
tree | bad48e5e45b10d5fc807b2f74da41cda68e18ab3 | |
parent | 0ef0c1994b050b35b50d0f3f4a0fe1c4c67f1072 (diff) | |
download | gitlab-ce-docs-style-and-structure-improvement.tar.gz |
Initial edits to style guide.docs-style-and-structure-improvement
-rw-r--r-- | doc/development/documentation/styleguide.md | 11 |
1 files changed, 6 insertions, 5 deletions
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index c0386290785..b065b16f46c 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -50,17 +50,18 @@ yield a useful result, and ensuring content is helpful and easy to consume. - '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 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. If an outside source - that's under copyright, rephrase, or summarize and link out; do not copy and paste. - All applicable subsections as described on the [structure and template](structure.md) page, with files organized in the [correct directory](index.md#documentation-directory-structure). + - Any media types/sources, if relevant to readers. You can freely + include or link presentations, videos, etc.; no matter who it was originally composed for, + if it is helpful to any of our audiences, we can include it. + - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone. + - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source. - To ensure discoverability, link to each doc from its higher-level index page and other related pages. - 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. -- Do not duplicate information. +- To avoid duplication, do not include the same information in multiple places. Instead, choose one 'single source of truth (SSOT)' location and link from other relevant locations. - Structure content in alphabetical order in tables, lists, etc., unless there is a logical reason not to (for example, when mirroring the UI or an ordered sequence). |