summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMike Lewis <mlewis@gitlab.com>2019-04-08 02:58:31 +0000
committerMike Lewis <mlewis@gitlab.com>2019-04-08 02:58:31 +0000
commit7d59593bf65308f680df40d442e88373a26b3626 (patch)
treebad48e5e45b10d5fc807b2f74da41cda68e18ab3
parent0ef0c1994b050b35b50d0f3f4a0fe1c4c67f1072 (diff)
downloadgitlab-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.md11
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).