Re: [xwiki-devs] [Proposal] Do not write pure-developer release notes

On 30 Jan 2019, at 18:09, Marius Dumitru Florea <mariusdumitru.florea(a)xwiki.com> wrote: Yes, it looks nice, but SonarQube is a different kind of product. I don't think it's a development platform like us..

On Wed, Jan 30, 2019 at 6:41 PM Vincent Massol <vincent(a)massol.net> wrote: > 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 <vincent(a)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 >> > >