10 guidelines to a great Solution - WORK IN PROGRESS

This guide describes best practices and guidelines to write Solutions to support cases for publication in our knowledgebase or release to the public.

Background

The resolution of support cases often results in a good amount of documentation being produced, consisting of email exchanges, attachments, tasks and call logs, etc. As Ubuntu systems support analysts, we need to always keep in mind that the goal of each and every cases' resolution is to have a documented trail of how to solve the specific case. Although every case may not be material for an F.A.Q., we need to consider the possibility it may happen more than once, and as such, produce the most generic, easy to follow instructions to reproduce its complete resolution.

1. Don't reinvent the wheel - Search the current solutions and see if someone hasn't already written one that matches your case. If there is one, augment and improve it. Search external documentation sources, inquire about their licencing and if possible, integrate information from other sources

2. Don't be personal - Try not to start sentences in the first person "I no tried to edit the configuration file..."

3. What version are you using ? - When referring to package names, linux kernels, distributions, etc., state the full name and version.In Ubuntu 6, you can... becomes In Ubuntu 6.06.1 (Dapper Drake) you can...

4. Don't skip steps - Don't assume the person following steps of a solution knows what to do. Use templates or shortcuts to re-use text efficiently.Enable the universe repo by editing the sources file would become

   1. Open a terminal window
   2. Open the /etc/apt/sources.list file for editing: sudo nano /etc/apt/sources.list
   3. Find XXXX and replace it with XXXX so the "Universe" repository is active
   ...

References

• http://debaday.debian.net/contribute/