summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorMarcia Ramos <virtua.creative@gmail.com>2017-03-27 20:06:16 -0300
committerMarcia Ramos <virtua.creative@gmail.com>2017-03-27 20:06:16 -0300
commit38f092d197e44c2fa8be8eb1ce6a1ae0e306f24c (patch)
tree4f036da1b9629f31e69a1961f8b5a468763667cf /doc
parente70ed3a1c6be1406e2d53c9886a92686947eabf1 (diff)
downloadgitlab-ce-38f092d197e44c2fa8be8eb1ce6a1ae0e306f24c.tar.gz
link to comm writers page, add what is a tech overview + example
Diffstat (limited to 'doc')
-rw-r--r--doc/development/writing_documentation.md11
1 files changed, 9 insertions, 2 deletions
diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index 194bd26cd24..1f65b863a36 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -1,7 +1,7 @@
# Writing Documentation
- **General Documentation**: written by the developers responsible by creating features. Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers.
- - **Technical Articles**: written by any GitLab Team member, GitLab contributors, or Community Writers.
+ - **Technical Articles**: written by any GitLab Team member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/).
- **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs, in the same merge request containing code.
## Distinction between General Documentation and Technical Articles
@@ -27,7 +27,9 @@ They live under `doc/topics/topic-name/`, and can be searched per topic, within
- **Technical Overviews**: technical content describing features, solutions, and third-party integrations
- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach very specific objectives
-#### Understanding Guides and Tutorials
+<style></style>
+
+#### Understanding Guides, Tutorials, and Technical Overviews
Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 > 3 > 4 > 5 (B)`.
@@ -39,6 +41,11 @@ A **tutorial** requires a clear **step-by-step** guidance to achieve a singular
- Live example (on the blog): [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/)
+A **technical overview** is an overview of that feature. It describes that it is, and what it does, but does not walks
+through the process of how to use it systematically.
+
+- Live example (on the blog): [GitLab Workflow, an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/)
+
#### Special Format
Every **Technical Article** contains, in the very beginning, a blockquote with the following information: