31 Jan
2019
31 Jan
'19
9:24 a.m.
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. 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 <vincent(a)massol.net>et>, wrote:
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..
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 <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
> >
>
>