If you want to create an issue in the repository, please follow this guide, to ensure that your ticket has the greatest likelihood of being actioned.
When creating a good title and body, bear the following points in mind:
- Be concise and descriptive
- Write in the active tense
- Start the title with a verb
- Use bullets and images where appropriate
Let’s expand on those four points. Ensure that the issue has a descriptive, yet concise, title. Make sure that the title uses the active tense and, ideally, starts with a verb and is no longer than 80 chars.
The reason for this is that, as with search results, a title is the first (and perhaps only) thing that people will read. So, it has to quickly convey what the issue is for.
Active tense requires less effort to read, and often contains fewer words. So it’s far more effective than the passive tense. What’s more, by starting with a verb, it’s even clearer as to what’s being asked.
For example, instead of:
Procedure for publishing a new branded iOS app
Rewrite it as this, instead:
Update the procedure for publishing a new branded iOS app
Ensure that it has a descriptive, yet concise, body. Please, write as long as you need to, but no longer. You should aim to provide as much information as you need, but try not to waffle. The body supplements the title, expanding on what the title cannot say. However, it’s not War and Peace.
When formatting the body, bullet points are likely easier and quicker to read through than large paragraphs. But whichever conveys the information the best is the one to choose. So, there’s no hard and fast rules.
If images are applicable, please use them. Sometimes, borrowing the old cliché, "a picture is worth a thousand words". If so, then use an image and save time and effort.
Currently, there are only two milestones: 10.0 (the next release) and "Documentation Backlog". Normally, you should put the issue straight in "Documentation Backlog". But, if it’s urgent, add it to 10.0.
The next thing to do is to categorise the ticket with one, or more, labels. These are effectively categories, which make the ticket easier to search and filter on. If an applicable label isn’t available, please choose the next best one, or create a new label (following the existing style) and add it to the issue.
Finally, depending on the nature of the issue, either assign one or more users to the Issue, or mention the @owncloud/doc group in the issue’s description or comment.