New documentation articles: guides, tutorials, and tech overviews
What
We decided to publish all technical content in the docs instead of the blog, including:
- Tutorials (how-tos)
- Tech Overviews
- User Guides
- Admin Guides
We are willing to make any tech material as part of the documentation, as a single source of truth, including articles written by the community writers (in a new version of the program).
The GitLab Blog would be filled with non-technical content, much more related to marketing, culture, and announcements.
What's what?
Currently, we have two sources of technical content in GitLab:
- Technical blog posts
- Videos (YouTube)
- Documentation
- User docs
- Admin docs
- Developer docs
With the new model, we'll have:
- Documentation
- User docs
- Admin docs
- Developer docs
- User guides (to guide the conventional GL user from point A to point B)
- Admin guides (to guide the admin user from point A to point B)
- Tech overviews (product and feature overviews)
- Tutorials (how-tos)
- Indexes (high-level pages which link to everything related to that topic - videos, old posts, all the related docs)
Blog posts will eventually present tech content, but related to GL core ideas, proposals, and decisions. We can also eventually use the blog to promote tech content available in the documentation.
Notes:
- Technical documentation: user, admin, and dev docs are the responsibility of the developers to create and maintain up-to-date.
- Community writers tech articles will be published in the documentation, as guides, tech overviews, or tutorials.
Distinction
The new tech content will contain a note at the beginning, explaining the type of article, the knowledge level required to follow along, and the author's name:
> Type: tutorial
> Level: intermediary
> Author: [XXX XXX](link-to-gitlab-com-handle)
Attribute the author - discussion here: https://gitlab.com/gitlab-com/gitlab-docs/issues/87
Styleguide
Follow the same style guide - https://docs.gitlab.com/ce/development/doc_styleguide.html
Writing tutorials, overviews, and guides
Use the writing method defined for tech blog posts prior to this new model.
Improvements necessary
- Create index pages per topic
- Move from redcarpet to kramdown: https://gitlab.com/gitlab-org/gitlab-ce/issues/18552 and https://gitlab.com/gitlab-com/gitlab-docs/issues/50
- Create, discuss, and approve the new version of the community writers program
To be discussed / approved: @seanpackham @axil