Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
1
Merge Requests
1
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
nexedi
gitlab-ce
Commits
9707faca
Commit
9707faca
authored
Aug 03, 2020
by
Mike Jang
Committed by
Mike Lewis
Aug 03, 2020
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Elaborate on authoritative sources in Docs Style Guide
parent
d038ca24
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
32 additions
and
1 deletion
+32
-1
doc/development/documentation/styleguide.md
doc/development/documentation/styleguide.md
+32
-1
No files found.
doc/development/documentation/styleguide.md
View file @
9707faca
...
...
@@ -827,9 +827,40 @@ Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help
### Links to external documentation
When describing interactions with external software, it's often helpful to include links to external
documentation. When possible, make sure that you
are linking to an
**authoritative**
source
.
documentation. When possible, make sure that you
're linking to an
[
**authoritative** source
](
#authoritative-sources
)
.
For example, if you're describing a feature in Microsoft's Active Directory, include a link to official Microsoft documentation.
### Authoritative sources
When citing external information, use sources that are written by the people who created
the item or product in question. These sources are the most likely to
be accurate and remain up to date.
Examples of authoritative sources include:
-
Specifications, such as a
[
Request for Comments
](
https://www.ietf.org/standards/rfcs/
)
document
from the Internet Engineering Task Force.
-
Official documentation for a product. For example, if you're setting up an interface with the
Google OAuth 2 authorization server, include a link to Google's documentation.
-
Official documentation for a project. For example, if you're citing NodeJS functionality,
refer directly to
[
NodeJS documentation
](
https://nodejs.org/en/docs/
)
.
-
Books from an authoritative publisher.
Examples of sources to avoid include:
-
Personal blog posts.
-
Wikipedia.
-
Non-trustworthy articles.
-
Discussions on forums such as Stack Overflow.
-
Documentation from a company that describes another company's product.
While many of these sources to avoid can help you learn skills and or features, they can become
obsolete quickly. Nobody is obliged to maintain any of these sites. Therefore, we should avoid using them as reference literature.
NOTE:
**Note:**
Non-authoritative sources are acceptable only if there is no equivalent authoritative source.
Even then, focus on non-authoritative sources that are extensively cited or peer-reviewed.
### Links requiring permissions
Don't link directly to:
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment