Hi Denis, > On 31 Jan 2019, at 09:24, Denis Gervalle <d...@softec.lu> wrote: > > Hi Vincent, > > Maybe, we need to introduce an Advanced checkbox in the RN, and publish it in > two parts. One part would be expanded, and very visible, and the other one, > need some action from the user to be shown. Normal users will therefore get > what you expect, and more interested people still have that insightful > information they delight.
I think this could be implemented with https://jira.xwiki.org/browse/RN-45 Thanks -Vincent > As an advanced user, I really don’t see JIRA as release notes, since JIRA > also contains a bunch of very non-significant information, and the way the > issue is written, is also sometimes confusing since it might contain a > discussion. Reading a list of JIRA issue is not a usual way to be updated, > you check them mainly when you have a specific problem. > > Just my thought as an interested user of some technical highlights. And I > most agree with your remarks about the way those note are written, there is > plenty of room for improvement there, to really distinguish them from the > JIRA issue. > > Thanks, > > -- > Denis Gervalle > SOFTEC sa - CEO > On 31 Jan 2019, 08:27 +0100, Vincent Massol <vinc...@massol.net>, wrote: >> >> >>> On 30 Jan 2019, at 18:09, Marius Dumitru Florea >>> <mariusdumitru.flo...@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.. >> >> Yes (although you could argue about that). However I still believe that to >> attract and keep users (which is our primary objective IMO), we should focus >> on RN for users (Highlights only and not 100% transform JIRA issues into RN >> items) and for developers simply link to reference documentation. >> >> In other words, focus on quality vs quantity for the RN. Our full RN is the >> JIRA list. Our RN page is supposed to be an extract of the full JIRA list. >> >> Am I the only one to think this? :) >> >> Thanks >> -Vincent >> >>> >>> On Wed, Jan 30, 2019 at 6:41 PM Vincent Massol <vinc...@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 <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 >>>>> >>>> >>>> >>
