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 or upcoming 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

Blog Communication

https://openbuildservice.org/blog

The blog is mainly used to communicate the news about OBS. We publish new blog posts periodically about meaningful improvements and new features.

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

Readers: current users of OBS.

Tips:

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

Body Text

• Start with a lede, an initial paragraph describing briefly who, what, where, when, why, and how.
• Be concise: use short sentences, short paragraphs, and short overall messages.
• Use simple words.
• Use active voice.
• Make it easy to skim: use several headings and subheadings, create bulleted and numbered lists, include images, etc.

References:

• Writing a Compelling, Informative News Lede
• 20 Killer Web Copywriting Tips
• Journalism Skills for Engaged Citizens
• Thoughtco articles about writing
• Copywriting Dos and Don'ts
• Refactoring: A developer's guide to writing well (video)