31 Jan
2019
31 Jan
'19
11:23 a.m.
Hi,
What I don't like about this is the fact that, because of the rule that
says that all closed issues must have assigned documentation links
(including in the RN), the developer now has to make yet another decision,
and a pretty subjective one, this time. You (the dev) need to decide if the
issue you've just worked on is RN worthy... a decision that can be
problematic at multiple levels and I foresee possible friction (e.g. you
believe you're done with your issue and, on the last minute or at release
day, someone starts telling you that it should have been documented in the
RN, when you had previously decided that it was not the case).
Re "Developers", I also prefer to keep it and to target both "advanced
users" and "platform users" (i.e. extension devs that would normally be
interested in API changes). IMO, it's more important to focus in the RN on
explaining what *changes* in the platform's behavior with the modification
that was performed, nor only in explaining what the modification does.
Also, AFAIR, we used to consider the issue tracker as "ephemeral" so the
fact that we are listing the issues that might be gone at some point might
no be very helpful on the long run.
So I see the proposal as slightly conflicting with the potentially
vanishing list of issues and the rule that requires dev to always document
(including in the RN).
IMO, we already deploy an "importance" ordering and we have the
Miscellaneous section that readers can easily skip. I agree with Marius
when he says that XWiki and SonarQube are completely different beasts.
An even more extreme approach, building on what Denis suggested, is to
break the RN into completely separate pages, for Users, Devs and Admins...
but I just feel we're creating busy work for ourselves at this point...
IMO, our current approach works. Sure, we might have to avoid cryptic lines
in the Miscellaneous section, but that's something we can improve.
Thanks,
Eduard
On Thu, Jan 31, 2019 at 10:36 AM Vincent Massol <vincent(a)massol.net> wrote:
On 31 Jan 2019, at 09:24, Denis Gervalle
<dgl(a)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. 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.
Thanks Denis. Good feedback
I agree. There’s just one aspect to take into consideration: the cost :)
In the end it’s a cost/benefit ratio. Also we document in the reference
documentation so for me just links to reference doc for developer changes
could be enough (especially if we use the “Since XXX” information in the
reference doc).
Thanks
-Vincent
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
>>>>
>>>
>>>
>