From 38f092d197e44c2fa8be8eb1ce6a1ae0e306f24c Mon Sep 17 00:00:00 2001 From: Marcia Ramos <virtua.creative@gmail.com> Date: Mon, 27 Mar 2017 20:06:16 -0300 Subject: [PATCH] link to comm writers page, add what is a tech overview + example --- doc/development/writing_documentation.md | 11 +++++++++-- 1 file 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: -- GitLab