diff options
| author | Marcia Ramos <virtua.creative@gmail.com> | 2017-03-27 20:06:16 -0300 |
|---|---|---|
| committer | Marcia Ramos <virtua.creative@gmail.com> | 2017-03-27 20:06:16 -0300 |
| commit | 38f092d197e44c2fa8be8eb1ce6a1ae0e306f24c (patch) | |
| tree | 4f036da1b9629f31e69a1961f8b5a468763667cf /doc/development/writing_documentation.md | |
| parent | e70ed3a1c6be1406e2d53c9886a92686947eabf1 (diff) | |
| download | gitlab-ce-38f092d197e44c2fa8be8eb1ce6a1ae0e306f24c.tar.gz | |
link to comm writers page, add what is a tech overview + example
Diffstat (limited to 'doc/development/writing_documentation.md')
| -rw-r--r-- | doc/development/writing_documentation.md | 11 |
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: |