BTW I really like the quality of the SonarQube release notes: * Not too much (nobody reads when there’s too much) * Only document important highlights and make the RN nice for them (nice screenshots, nice doc)
https://www.sonarqube.org/sonarqube-7-6/ WDYT? Thanks -Vincent > On 25 Jan 2019, at 09:31, Vincent Massol <vinc...@massol.net> wrote: > > Hi devs, > > Context > ======= > > It’s been since we’ve deviated from the original purpose of the Release Notes > by also adding developer-oriented release notes. > > The goal of the Release Notes was to **highlight** important novelties for > our **users**, because looking at the JIRA list is too technical (otherwise > we could simply use the Release feature of JIRA! :)). > > So you may ask why we do have a “Developer” Category in the RN app. These > were not for pure developers but for XWiki users who are more advanced and > can write scripts in wiki pages. And when it’s the case we **must** add > examples, otherwise, it’s completely useless. > > For example this morning I saw this RN added: > https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/11.0/Change004/ > > This is typically something that has very little value to me: > * It’s for pure developers (java devs) > * It’s not understandable by anyone except the person who coded it or > participated to the dev mailing list discussion about it > * It doesn’t say more than what’s in the JIRA issue so what’s the point? > * There are no examples at all in it! > * Real developers can simply look at the reference documentation or can read > the JIRAs. We always link the JIRA issues in the RN anyway (it was for this > reason that we’re listing them). > * It takes time to write RN items and thus it needs to have high value > > Proposal > ======== > > * Go back to the original idea and only list developer RN items when they are > for scripting users and not APIs. For example, document some new script > service or some additions to existing script services. Of course Groovy would > allow you to call any API so being able to use it from Groovy is not a good > criteria. I’d say that the criteria should be whether the Release Note Change > is useful for Velocity users. > * Rename “Developers” into “Scripters” or or “Advanced Users” (any better > name?) > * Always put an example when writing a “developer” change and take the time > to explain properly what it’s about. > > WDYT? > > Thanks > -Vincent >
