New docs - guides and articles
What
Give attribution to authors in new docs articles
Context
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.
How to do it
That said, I think it's fair to give attribution to the author of the content, as a note at the end, or at the beginning of the text, together with the content type and required knowledge level.
Example:
> Type: tutorial
> Level: intermediary
> Author: [XXX XXX](link-to-gitlab-com-handle)
I had done something like that to the new GL Pages user guide:
> Type: user guide
> Level: beginner
But somehow it's not there anymore. It is very important to provide this simple piece of info to the reader, as it will tell them what kind of doc is that, and the level of knowledge required to follow along.
If we are publishing technical articles on the documentation instead of on the blog, that's great, but we need to stick with some standards (e.g. professional writing techniques), and distinguish a technical article, tutorial, or guide, from a user or an admin doc.
Why
- I don't think it's fair to publish an article without giving attribution to the author. I spoke to a few people and they raged to the perspective of having their content published without giving them attribution.
- As part of the community writers program, I don't think people will join the program to publish something that there's no attribution to them at all
- From a career point of view, it doesn't make sense to invest time on something that will not credit you for anything.
I know we had thought on publishing a blog post to promote the author, but it would take a lot more time than simply attributing the author on the article itself. Also, a blog post gets behind in a week or so. Just imagine how would you put your article in a portfolio: would we need to link to the doc we wrote and to a blog post that says we wrote it? Sounds weird to me.
Once the doc is published, we can promote the new doc article on social media, as we do for blog posts.
cc/ @seanpackham @axil @JobV