Release Notes Explained in Fewer than 330 Characters

What is a release note?

The release note is a document, written by technical writers, that are shared with the clients of the software products. The document is released as a part of the final build that contains the following:

  • New enhanced features
  • Deprecated features
  • Known bugs
  • Fixed bugs
  • Migration path
  • Upgradation path
  • Advisory notes and rules
  • Customer support notes


Release Note Format


  • Name of the document with the product name
  • Release number
  • Release date
  • Release note date
  • Version

For example, make the heading in big and bold in the following format :

[Product Name] [Version Number] Release Notes


An overview of the product contains changes to the recent software version along with the system requirements. Links to installation instructions, user manual, and release notes archive can also be included for best practices.


The purpose of the release note is to update what is new in the release in the current build. Break the release notes document into sections, each with its own headings. The  following sections may be considered :

  • New enhanced features
  • Deprecated features
  • Known bugs – Companies with open source projects, with enough of user base, are usually transparent with known defects since they have a public tracking system. However, this sort of decision is usually made defect by defect basis, by keeping in mind the security and stability liability of the company.
  • Fixed bugs
  • Summary of the issue along with the resolution.
  • End-user impact – What different actions are needed by the end-users of the software application. This includes whether other functionalities are impacted by these changes.
  • Migration path
  • Upgradation path


A release note is usually a summary of recent changes, enhancements and bug fixes in a particular software release. It is basically a list of bullets with the actual brief necessary descriptions. It is preferable to keep the information on the document scannable.

Release notes are frequently written in the present tense. It provides information to the client that is clear, correct, and complete. 









Collaboration Using Confluence

Confluence is the fastest-growing collaboration tool. It is a very user-friendly tool to do the best work from anywhere and any device. It is a platform which aligns the team members even in different locations to get the project across the finish line.

Confluence helps to manage scattered information. It makes it easy to find what you need and when you need. Team members use it to interact and communicate efficiently. Users can easily create blogs and pages in Confluence which can be commented on or edited by anyone in the team. Team members can brainstorm ideas and bring all the necessary information. Users can give feedbacks in contexts instead of going back and forth with email threads.

You can quickly handoff requirements for development and stay updated on the progress with fewer meetings. Everyone can see it and move forward. Ones your plan is in place it is easier to share with other teams too. Work is never lost where you or your team can access things right away.



WHAT IS MARKDOWN? Markdown logo

Markdown is a light weight mark up language with simple text formatting syntax. It is suitable for organised pieces of content in web that smoothly converts to clean and structured HTML. It was designed with the explicit intention to be easily readable.

The traditional writing user interfaces causes unnecessary interruptions in the flow of thought process whenever user has to pause and click their mouse or use complex short-cut keys for writing. Therefore, the advanced writers find it very convenient to apply rich document formatting on the fly seamlessly.

Markdown is extensively used by github .


The basics syntax of Markdown is pretty simple.
Here are some of the basic elements often used:


Use any line as a heading by prefixing with # symbol
Heading 1 is prefixed with one #
Heading 2 is prefixed with two ##
Similarly, Heading 3 with ###
For example:

# Heading 1



## Heading 2




Emphasize texts by using italics , bold or both italics and bold easily, with the help of either asterisks or underscores.
A text can be wrapped up in a single asterisk (*) to make it italics.
It can be wrapped with double asterisk ( ** ) to make it bold.
Or triple asterisk ( *** ) to make it bold and italics.

For italics


For bold


For bold and italics

***bold and italics***


There are two types of links :

  • Inline links
  • Reference links

Wrap the text to be linked, in a square bracket ’ [ ] ’ , followed by the URL to be linked to in parenthesis ’ ( ) ’ in order to add a link.
i,e [text] followed by (URL)

[Markdown official website](


As the name implies the reference link is actually a reference to another place in the document.
It is written as [ text ][ xyz ] . Now you can define the link anywhere in the document [ xyz ]: URL



The syntax of inserting an image is similar to that of links. The only difference is that you need to prefix an exclamation mark ’ ! ’ in front of text wrapped in square bracket ’ [ ] ’ followed by the URL in parenthesis ’ ( ) ’ .
i.e ![ text ] followed by (URL of image).

![text](URL of image)

For a reference image follow the same pattern as reference links. Images can be inserted in the similar way as reference links by defining it later.



There are two type of lists:

  • Unordered list
  • Ordered list


To create an unordered bullet list, you need to preface each item in the list with an asterisk ( * ) or (+) or (-) . For example:

* Butter
* Bread
* Apples
* Eggs

The Markdown list would be represented by the following bullet points:

  • Butter
  • Bread
  • Apples
  • Eggs

You can also create nested lists by putting four spaces and it will be nested under the line above.


For ordered list, prefix a number followed by a dot and space, before the text.

  1. Butter
  2. Bread
  3. Apples
  4. Eggs


End a line with two or more spaces.


Three or more dashes ( – ) or asterisks ( * ) is used to throw-down a quick divider in your article to denote a visual separation between different sections of text.


* * *

- - - - 

Horizontal rules


Markdown’s block quote syntax is useful when a sentence or a paragraph taken from another source, calls to draw a special attention to the reader.

To create a block quote you have to preface a line with the “greater than” sign ( > ). For example

> Peace begins with a smile.

Peace begins with a smile.


If you’re a technical writer, you may want to use example snippets of code to explain your readers a particular syntax. Use a single back-tick ( ` ) around a word in a sentence, to show a quick code snippet.

Example of an inline code snippet.

Similarly, to create code blocks place triple back-ticks ( “` ) before and after the code block. A blank line before and after code blocks makes the raw formatting easier to read.

For Example:

Code snippet

int main(int) {
    std::cout << "Hello World" << std::endl;
    return 0;


Escaping Markdown characters with a back-slash \ allows you to use any characters which might be getting accidentally converted into HTML.
For Example to write * do not convert into italics* literally without appearing in italics:

\* do not convert into italics\*


<button class="button-save large">Big Fat Button</button>

Possibly the coolest feature of Markdown is that it also supports plain old HTML. If you find yourself stuck and unable to do what you want in Markdown you can simply write in regular HTML and it will work just fine.


If you’re just getting into Markdown and you’ve found yourself with a massive back-log of old files which are written in HTML, you might want to convert them to Markdown to make them easier to work with in future.

Here’s a tool by Dom Christie which lets you do that exactly.


Here are some of our favorite Markdown editors for Mac, Windows desktop and mobile.






Publishing with StackEdit


I am sure now your fingers will be flying across the keys to speed up your workflow while you pen your piece of writing. Become a pro by practicing writing with Markdown!

Please feel free to ask if you have any questions.

3 Secrets of Great Writing Skills

pen writing notes studying
Photo by Tookapic on

There are some secret techniques for the dynamics of great writing.

If you want your writing to stand out of the crowd, let’s take a step back and think what actually a “good” or a “bad” writing is.

A piece of good writing is associated with some basic characteristics.

  • It is very clear in its expressions.
  • It captures the interests stirring the emotions of a reader.
  • A good writing flows very smoothly.

On the other hand a “bad” writing is boring and doesn’t capture a reader’s imagination.

It is ambiguous and confusing and the rhythm is very uninspiring.


The Purpose


Deliver Information– It informs the people of something useful.

Entertainment– a good piece of writing makes people fascinated.

Persuade– It convinces people to take a stand on some issue like in an editorial of a newspaper and

Inspire– in order to motivate people


The Mindset of an Elite Writing

  • You should be able to create the refinement by taking every word seriously.
  • You should have a strong intention to connect to the audience. You got to know their values, beliefs and perception. So you need to basically tailor your piece of writing according to their existing mindset.
  • Keep your writing real, honest and original and not something fancy or over the top. The aim of the writing is to communicate and not to impress the audience.
  • Give attention to details. Like all the headings should be starting with a capital letter and all the dashes should be of the same distances used every time. This will make people feel great and these approaches will definitely raise the level of your writing.


The Key Elements

  1. Simplicity
  2. Clarity
  3. Elegance


Here is the deal, you need to maximize and optimize each of these three elements. There are certain principles to be applied.


1.Simplicity Principles:

woman s hand using a pen noting on notepad
Photo by Kaboompics .com on


Be Economical– Use shorter words except for precisions and elegance. Use fewer words whenever feasible. Shortened words are faster to read and quickens comprehension. However, there are always exceptions.

Avoid redundancy- Repeating a point over and over again is something that needs to be erased. Sleek writing is more impactful until an emphasis is made deliberately or to give a poetic effect.

Plainer is nicer- Don’t over complicate things. Simplify writing to the highest possible degree. Avoid giving the readers unnecessary strain as they have to unwind it in their minds. Aim to keep your writing plain and as familiar sounding as possible.

Less is better-  Don’t give too much information to the reader. Sleek writing creates a kind of dramatic effect but giving too much information makes it unappealing to the audience. Tailor the amount of details for specific audience.

Overstretching- Avoid using lots of sub clauses as it makes difficult for readers to concentrate and grasp the point. Use active sentences instead of  passive sentences. It forms quick visual images in the minds of the readers. Avoid capitalization of words unnecessarily within sentences. This disrupts the comprehension.


2.Clarity Principles:

adult books business coffee
Photo by Burst on


Avoid fuzzy thinking– Get clear what you are trying to say before you say it. Be very specific and make logical connections of the ideas that you want to convey. Prevent the reader’s mind going blank. Spell out things, don’t force readers to make inferences.

Eliminate jargon–  You should always strike off anything that smells of jargon. There won’t be an emotional impact if it is used. It takes away the clarity, freshness and liveliness from the writing.

Unambiguous– is one of the important point to embed. Eliminate every doubt. Ambiguity is one of  the biggest killer of comprehension.

Crisp Distinctions– You have to make sharp contrast between ideas that are in opposition. The sharper the contrast the more vivid the sentence will be. Use punctuation to help sharpen comparisons. Make abundantly clear what you are comparing.

Remove clutter- Comprehension is badly affected if a sentence is cluttered. The idea is much clear when clutter is removed.

Don’t mix tenses– Keep your tenses consistent. Smooth out of all conflicting time elements. Writing loses quality when tenses are switched.

Refrain from using curly sentences–  Untangle sentences to the furthest extent possible. Don’t force readers to do mental gymnastics.


3.Elegance Principles:

person woman desk laptop
Photo by Breakingpic on


House Style– Adopt your own style rules. It includes punctuations, headings, lists, underlining words in bold or italics, the dashes the spaces etc. Be consistent throughout as it adds a certain resonance to the writing. It will make you look organised, authoritative and professional.

Unsightly Widows- Sometimes there are stray words at the end of paragraphs that tend to give an imbalanced look. Try to iron those out. Blocks of texts which looks well balanced is something pleasant to read and definitely adds elegance.

Pristine Paragraphs- Make your paragraphs short. Shorter paragraphs are neat and sleek. Longer ones tends to take away the enthusiasm of a reader. People are more interested in shorter paragraphs as they get a seamless experience to get a flow of idea.

Word Echos- Avoid repetition of same word in subsequent sentences or same sentence. These words lack sophistication. Strive never to use same word in close proximity.

Alternative words- Use alternatives to regularly used words as it adds a sense of variety in your writing. Keep the alternative words handy. Be creative as it will give a little bit of rhythm and flare to your writing.

Narrative Elegance- Take a bird’s-eye view of the entire piece of writing as blocks of ideas and sections. It should be clear to you what point you want to make in each section and how it is going to flow logically.



black click pen on spring notebook
Photo by Pixabay on

So these are basically the  foundations of an elite writing.

You can make a habit initially to keep a checklist, while writing, with important questions like:

  • Did I use simple familiar words?
  • Did I eliminate all jargon?
  • Have I avoided redundant words?
  • Did I refrain from ambiguity?
  • Did I give too much of information?
  • Can I shorten the sentences ?
  • Have I used an active voice?
  • Am I specific and precise in conveying my ideas?
  • Are all my sentences in correct ordered?
  • Do I have logical connections in all my sentences?
  • Are my paragraphs shorter?
  • Am I avoiding to make simple point sound complicated?
  • Did I avoid mixing up tenses?
  • Are all my styles consistent?


Hope you have found this blog useful. If you have any questions please feel free to ask.