10 points to write easy-to-understand and useful release notes
Writing better release notes
https://simonwillison.net/2022/Jan/31/release-notes/
'Release notes are an important part of the open source process,' Wilson said, arguing that proper release notes are important when releasing open source projects on GitHub and elsewhere. Wilson, who recently thought about 'how to write good release notes,' summarizes the following 10 points when writing release notes.
◆ 1: Write the release notes
This may sound like a joke, but Wilson says it's serious. 'If you want people to take advantage of the work you've done to improve a project, you have to let people know about the project!', Saying the importance of writing the release notes themselves. increase.
◆ 2: Enter the date
Being dated in the release notes for a software release allows users to know which version is the latest and to choose a more feature-rich and less buggy version.
◆ 3: Create a link to the release notes for each version
It is also important to include links to the release notes for previous versions, such as at the end of the release notes. Of course, Wilson recommends that the format be such that viewers can immediately recognize it as a link to past release notes.
◆ 4: Divide the content by header
When there are many contents of the release notes, it will be easier to read if you divide them by the header for each topic, such as 'new function this time' and 'bug fix'.
◆ 5: Emphasize the important part
Even if you create a release note that contains all the information about the version, if the reader does not understand it, it will be overwhelming. Therefore, it is important to emphasize and clarify the important parts of the version.
◆ 6: Link to related documents
The release notes are concise for users, but for engineers who want to know more in-depth information, it is helpful to add links to specialized related documents.
◆ 7: Use examples and screenshots
Wilson said, 'Most of the release notes are tasteless and odorless. There is no limit to the amount of release notes, so you are free to use any tool to answer the question,'What has changed and why is this important?'' Please use, 'he insists that it should be explained in an easy-to-understand manner using examples and screenshots.
◆ 8: Insert a link to the related thread
For projects such as GitHub, a software development platform, you can get a better picture by linking to a thread about changes in the new version.
◆ 9: List the contributor in the credit
If anyone has contributed to the development of the software, you should include the contributor's name in the release note credits and thank them.
◆ 10: Inform people that it has been released
It doesn't make sense to publish new software and release notes without anyone noticing. Wilson is announcing new releases through Twitter, personal blogs, newsletters, etc., and he needs to notify people in some way.
Wilson likes the release feature of GitHub very much. 'You can easily create releases attached to tags, and each release also includes a linkable page. Release notes are written in Markdown format for later editing, additions, typos, and more. You can fix the error. '
Also, in his own project, not only the technical changes are noted in the release notes, but also personal notes about new features, background to development, lessons learned in development, opinions on application of new features, etc. are annotated. It is said that he is trying to create release notes for.
Related Posts:
in Software, Posted by log1h_ik