Documentation and Communication

We have three main channels for documenting and communicating any relevant information about OBS : the official documentation, the GitHub's wiki and the blog.

Here we give you some tips about the appropriate way to write in those channels.

User and Administrator Documentation

https://openbuildservice.org/help

This is the official documentation where we explain all the functionalities and workflows provided by OBS.

The goal is to teach the users and administrators how to use the application.

Readers: experienced and inexperienced users and administrators of OBS.

Tips:

• Use the highest level of abstraction possible
• Give detailed explanations about functionalities and workflows
• Avoid giving implementation details
• Use a language that any new user, with a technical background, can understand
• Add examples of use when it is possible
• Images and workflow diagrams can be helpful

Developer Documentation

https://github.com/openSUSE/open-build-service/wiki

In GitHub wiki pages we can find the information that is relevant for current developers and future contributors: how to configure the development environment, how to deploy, architectural decisions, best practices, etc.

Readers: current developers and contributors with a technical background.

Tips:

• Use a low level of abstraction
• Go straight to the point
• Give implementation details
• Add links to relevant parts of the code or technical articles

Communication and Beta Features' User Documentation

https://openbuildservice.org/blog

The blog is mainly used to communicate the news about OBS. We usually publish a new blog post after each deliverable.

We also use the blog to write user documentation about new features in Beta. Those features are work-in-progress so we don't write official documentation about them until we release the final version. Meanwhile, we share the details of the new features in the blog, so interested users can start using and testing them.

Readers: experienced users of OBS.

Tips:

• Use a medium level of abstraction
• Go straight to the point
• Avoid giving implementation details
• Add links to other blog posts related to the topic

References:

Writing a Compelling, Informative News Lede https://www.thoughtco.com/how-to-write-a-great-lede-2074346

20 Killer Web Copywriting Tips https://writtent.com/blog/20-killer-web-copywriting-tips/

Journalism Skills for Engaged Citizens https://www.coursera.org/learn/journalism-skills

Thoughtco articles about writing https://www.thoughtco.com/writing-4133048

Copywriting Dos and Don'ts https://copyhackers.com/downloads/worksheets/Copy-Hackers-101-Copywriting-Dos-and-Don'ts.pdf

Refactoring: A developer's guide to writing well (video) https://www.youtube.com/watch?v=BbIILUSmSk4&list=PLbHJudTY1K0c8N1-PPyiQxlHNzJIzyJv6&index=43