Release Notes Style Guide

Submitted by biermannp on Tue, 07/09/2024 - 10:40

Along with each monthly release, we have a Release Meeting and publish Release Notes (internally). These help other members of the company understand what the Dev Team has been working on. The Release Meeting is more broad, and the Release Notes are more specific, covering topics we couldn't get to in the Release Meeting and going into more detail.

As a member of the Dev Team, you'll write release notes for (almost) every project you complete. Old release notes can be found in the J Drive under: J:\FullCount\Development\Docs\Build

Guide

If you have release notes for multiple projects in a month. Put each project's notes in separate Word files. Title each file in the following format: "YYYY-MM Descriptive Title Release Notes". Example: 2024-07 One Touch Ordering Release Notes.

Before each monthly release, email your release notes to both the Notes Compiler (currently Ryan Sweeney) and the Software Engineering Manager (currently Susan Junge), with the email subject line "YYYY-MM Release Notes".

Release notes are due the Monday before the release at noon. Release days are the second Tuesday of the month.

The primary audience of release notes is support, implementation, and sales personnel. The notes should be concise, easy to skim, and easy to reference. Notes are not an opportunity to show how much work you did. Sometimes two weeks of work gets a sentence, and two days of work gets a page.

Structure and Visual Styles:

• Use Microsoft Word default styles: Normal, Heading, Heading 2
• Place one Heading at the top of the file. Give it a short, descriptive title, such as a shortened form of the task name.
• Place zero to several Heading 2's throughout. The first Heading 2 should not be directly below the Heading. Instead, put a short summary.
• The notes body should be one or several non-indented paragraphs in the Normal style (Aptos (Body) Font Size 12).
• Terms that have a specific meaning should be Capitalized. If additional differentiation is needed, they can be put in "Quotes".
• Lists should be should be preceded with a description and a colon. Don't use a list for the top-level organization of your release notes

Images:

• Place screenshots and pictures at the end of your notes. Each image should have a short caption underneath. Don't add additional information in the images section.
• For legibility, screenshots should be taken on smaller screens (Imagine trying to view a desktop screenshot on a laptop or phone).
• Screenshots should be cropped to only show relevant information. Remove any blank space in the margins of the image.
• Not every change needs a screenshot. Only include a screenshot where it would help understanding. Try to include multiple changes in one screenshot.
• Images should have the "In Line with Text" Layout Option (This is default). Image layout can't be copy-pasted, and is hard for the Notes Compiler to recreate.

Grammar and Writing Styles:

• Use a declarative sentence structure: subject verb object.
• Writing should be clear and concise. Include all the information you need to communicate in the fewest number of sentences possible.
• Don't repeat yourself. When the same information is communicated in two different places and in two different ways, this is actually more confusing to read.
• Write each sentence in the most direct way possible. After you write a sentence, see if you can edit out 25% of the words but keep all of the same ideas.
• Use parallel sentence structures. For example, if the application has three different states, introduce each state with an identically structured sentence.

Example:

Below is an example of release notes that follow the effective writing guide above.

Kafoodle Integration

An integration with Kafoodle has been added to improve our nutrition and dietary offerings.

In the Back Office under the Community Info tab, you can now assign a Dietary System to connect with the community. Currently, Kafoodle is the only option.

Under Item Management, there is a new Pending Items subtab. The Pending Items subtab is only visible to communities that have Dietary Integration setup.

Items can have a status of Complete, Pending, or Ignore:

• An item with a status of "Complete" is fully setup, whether it comes from the Dietary Integration or is added normally. "Complete" items appear under the Items subtab.
• An item with a status of "Pending" has entered the system through Dietary Integration and is missing fields, including Tax Rate and Item Type, that need to be set manually. "Pending" items appear under the Pending Items subtab. Pending Items cannot be deleted. Instead, users can change their status to "Ignore".
• An item with a status of "Ignore" is only used for its dietary values and cannot appear on the menu. For example, Hollandaise sauce is an ingredient in other menu items, but is not a menu item itself. "Ignore" items appear under the Pending Items subtab. "Ignore" items have all fields disabled for editing.

For communities that have Dietary Integration setup, Back Office users are not allowed to change certain item fields that are set by the Integration. These include Description, Images, Ingredients, Nutrition Profiles, Dietary Tags, and Allergens.

A "Complete" Item

An "Ignore" Item

"Pending" Items cannot have their status changed to "Complete" until all required fields are set.