This article discusses the process of providing information in the Release Note field of Azure DevOps for both the Known Issues (before an item has been fixed) and the Release Log (after it has been fixed) lists.
The intent is to make this process as automated as possible; in the future we may be pulling directly from ADO to populate Web pages.
- Always begin with the phrase "A known issue exists" or "Resolves an issue" consistently. This makes it much easier to convert a known issue to a resolved issue using search and replace.
- Avoid skipping words or altering the pattern, such as, "Known issue exists..." or "An issue exists..." or "Issues exist..." or "Fixes an issue...." In normal writing, varying the structure and wording is preferable because it sounds more natural, but in this kind of writing it's detrimental to both the process of publishing and to reader's ability to scan and process information.
- Try to stick to the pattern of "A known issue exists where [subject/document/action] in [area/module] [verb and behavior] when [triggering condition]." or "A known issue exists where [triggering condition] causes [behavior] in [area/module]."
- What action is the trigger? In what module or document is the trigger encountered?
- What is the error, problem, or unwanted outcome?
- Is there a setting/combination of settings somewhere that causes the problem? Try to be as accurate with the name of the setting(s) as possible and indicate where to find it/them.
- When writing the Release Note, please review the Title as well, because it gets published with the Release Note field.
- If possible, use title case (AP style); refer to https://titlecaseconverter.com/ for more information and a quick utility.
- Remove the period from the end of the Title if one exists (even if it looks like a complete sentence).
- Try to remove any extraneous spaces between words. (Sometimes the folks creating the ZenDesk tickets put two or more spaces between words.)
General Guidelines:
- Try to avoid double quote marks where possible, and use single quotes instead. Because the text will eventually end up in HTML but passes through several layers to do so, double quotes sometimes end up in visible text as " instead of an actual punctuation mark and have to be manually corrected. Single quotes tend to cause less problems.
- Exception: use quote marks for literal text like an exact quote of an error message.
- Try to avoid the '>' character where possible.
- Wherever possible, include the exact error message wording instead of an approximation of it. This helps customers searching in ZenDesk find things that might not otherwise come up in a search.
- Replace any references to specific item IDs with placeholders such as the Field Name shown in Layout Editor with braces around it. For example, "Roster already exists on {date time} for Resource {resource}."
- Please stick to one space between sentences. (I know, I know...when I took Typing last century, they said to put two spaces after a period, colon, semi-colon, question mark, or exclamation point, but the rules have changed.)
- When mentioning a specific document, use the pattern "the [Document_Description] (DocID ####) document", e.g. "the Roster Time Off (DocID 11336) document". Try to be consistent with the capitalization of DocID and don't split it into "Doc ID".
- Try to avoid shorthand contractions, such as SB for Schedule Book.
- Capitalize file extensions (e.g. DOCX, XLSX) unless you are specifically quoting something in the user interface ("...when you click Save As and select the Excel (*.xlsx)-download option,").
- Try to keep trademark attributions in mind, e.g. Microsoft® by itself, and Microsoft Excel® or Microsoft Word® as products, and Mac™ or macOS™.
- Avoid mentioning customer names, specific dates, or versions. For example, "April 2 MediaPulse NFL Performance Issues" (original Title for #22930) breaks a whole bunch of rules.