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 are some tips about the appropriate way to write in those channels.

OBS 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 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 usage examples when 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 to developers and contributors: how to configure the development environment, how to deploy, architectural decisions, best practices, etc...

Avoid using other solutions like Etherpad, since it's hard to find documents again and we want to rely on a single solution.

Readers: current/future 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, technical articles or talks

Blog Communication

https://openbuildservice.org/blog

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

We also use the blog to write how-tos about new features in the beta program, 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: OBS users.

Tips:

• Use a medium/high level of abstraction
• Go straight to the point
• Avoid giving implementation details
• Add relative 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)