[xwiki-devs] [Proposal] Do not write pure-developer release notes
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
On 25 Jan 2019, at 09:31, Vincent Massol <[email protected]> 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/
Another example of a pure-dev oriented RN is: https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/11.0/Change002/ Thanks -Vincent
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
Hi guys, No opinions ? Thanks -Vincent
On 25 Jan 2019, at 09:31, Vincent Massol <[email protected]> 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
Hi Vincent, On 30/01/2019 09:05, Vincent Massol wrote:
Hi guys,
No opinions ?
Thanks -Vincent
On 25 Jan 2019, at 09:31, Vincent Massol <[email protected]> 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?
Actually reading the examples you give, I'm a bit mixed: I agreed that for the first one "the PropertyDisplayType" an example might be given: can be good to actually have the "example" box in the RN form. For the second one about legacy profile activated, actually I don't really know what's the impact for the users, and if he could change something about it. So I don't see how we could provide an example. So I have the feeling that the first one could be indeed adressed to Scripters (and even there, it's not a new scripting API, they could only use it in groovy scripts). And that the second one can be important for some administrators, but not for Scripters on the contrary. I might be wrong here but "Scripters" does not fit IMO and trying to find a new name might lead to create new categories actually. To be a bit more constructive I'd say that maybe for those changes we should not focus on a role but just say "Advanced changes". My 2 cents, Simon
Thanks -Vincent
-- Simon Urli Software Engineer at XWiki SAS [email protected] More about us at http://www.xwiki.com
I would also keep the term "Developers". Not sure why we would change that name. XWiki is a development platform, we have users that are developers. Thanks, Caty On Wed, Jan 30, 2019 at 12:37 PM Simon Urli <[email protected]> wrote:
Hi Vincent,
On 30/01/2019 09:05, Vincent Massol wrote:
Hi guys,
No opinions ?
Thanks -Vincent
On 25 Jan 2019, at 09:31, Vincent Massol <[email protected]> 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?
Actually reading the examples you give, I'm a bit mixed: I agreed that for the first one "the PropertyDisplayType" an example might be given: can be good to actually have the "example" box in the RN form.
For the second one about legacy profile activated, actually I don't really know what's the impact for the users, and if he could change something about it. So I don't see how we could provide an example.
So I have the feeling that the first one could be indeed adressed to Scripters (and even there, it's not a new scripting API, they could only use it in groovy scripts). And that the second one can be important for some administrators, but not for Scripters on the contrary.
I might be wrong here but "Scripters" does not fit IMO and trying to find a new name might lead to create new categories actually. To be a bit more constructive I'd say that maybe for those changes we should not focus on a role but just say "Advanced changes".
My 2 cents, Simon
Thanks -Vincent
-- Simon Urli Software Engineer at XWiki SAS [email protected] More about us at http://www.xwiki.com
I agree with Caty, but by "Developers" I understand "Extension Developers", who might be interested in new Java APIs (e.g. related to writing Java-based rendering macros). Of course, we should provide examples in the RN. Thanks, Marius On Wed, Jan 30, 2019 at 12:41 PM Ecaterina Moraru (Valica) < [email protected]> wrote:
I would also keep the term "Developers". Not sure why we would change that name. XWiki is a development platform, we have users that are developers.
Thanks, Caty
On Wed, Jan 30, 2019 at 12:37 PM Simon Urli <[email protected]> wrote:
Hi Vincent,
On 30/01/2019 09:05, Vincent Massol wrote:
Hi guys,
No opinions ?
Thanks -Vincent
On 25 Jan 2019, at 09:31, Vincent Massol <[email protected]> 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?
Actually reading the examples you give, I'm a bit mixed: I agreed that for the first one "the PropertyDisplayType" an example might be given: can be good to actually have the "example" box in the RN form.
For the second one about legacy profile activated, actually I don't really know what's the impact for the users, and if he could change something about it. So I don't see how we could provide an example.
So I have the feeling that the first one could be indeed adressed to Scripters (and even there, it's not a new scripting API, they could only use it in groovy scripts). And that the second one can be important for some administrators, but not for Scripters on the contrary.
I might be wrong here but "Scripters" does not fit IMO and trying to find a new name might lead to create new categories actually. To be a bit more constructive I'd say that maybe for those changes we should not focus on a role but just say "Advanced changes".
My 2 cents, Simon
Thanks -Vincent
-- Simon Urli Software Engineer at XWiki SAS [email protected] More about us at http://www.xwiki.com
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 <[email protected]> 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
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 <[email protected]> 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 <[email protected]> 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
On 30 Jan 2019, at 18:09, Marius Dumitru Florea <[email protected]> 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 <[email protected]> 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 <[email protected]> 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
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 <[email protected]>, wrote:
On 30 Jan 2019, at 18:09, Marius Dumitru Florea <[email protected]> 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 <[email protected]> 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 <[email protected]> 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
On 31 Jan 2019, at 09:24, Denis Gervalle <[email protected]> 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 <[email protected]>, wrote:
On 30 Jan 2019, at 18:09, Marius Dumitru Florea <[email protected]> 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 <[email protected]> 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 <[email protected]> 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
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 <[email protected]> wrote:
On 31 Jan 2019, at 09:24, Denis Gervalle <[email protected]> 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 <[email protected]>, wrote:
On 30 Jan 2019, at 18:09, Marius Dumitru Florea <
[email protected]> 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 <[email protected]>
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 <[email protected]> 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
Hi Edy,
On 31 Jan 2019, at 11:23, Eduard Moraru <[email protected]> wrote:
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).
Two points on this: 1) It’s already the case. The RM is supposed to check the quality of the RN and ask the devs to improve what needs to be improved. Like some dev doc missing examples or some cryptic wording, or missing images, etc. Or even missing doc when an issue is closed with N/A on the RN doc field in jira. 2) When an issue is closed, all devs see it and can comment (and we do comment already) if the dev closes with N/A and someone judges that it warrants some doc (FTR I also did comment a few times about issues that had RN changes documented but that IMO shouldn’t have any because it’s really too small a change to warrant being documented in the RN).
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.
Yes and also always add an example for using the API.
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.
Yes but so are Release Notes (ephemeral). They’re time-based (version-based to be precise but that’s time-based in practice). After some time we don’t support older versions and ideally we could even remove the RN for these old versions, similar to cleaning up our reference doc when we have too many “Since XWiki XXX” where XXX is very old.
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.
For me they’re very similar: they’re both products that are also a dev platform (see for ex https://docs.sonarqube.org/display/DEV/Extension+Guide and https://docs.sonarqube.org/display/DEV/API+Changes).
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…
Well the pages can be generated automatically but yeah I don’t like too much the idea. I’d prefer https://jira.xwiki.org/browse/RN-45
IMO, our current approach works. Sure, we might have to avoid cryptic lines in the Miscellaneous section, but that's something we can improve.
Yes it works (at a cost) except for Developer changes in RN which are sometimes cryptic, under-documented, without examples and sometimes unncessarily documented and too small to appear in the RN. And yes, we can solve this by asking the devs and the RM to be more careful about checking those. Thanks -Vincent
Thanks, Eduard
On Thu, Jan 31, 2019 at 10:36 AM Vincent Massol <[email protected]> wrote:
On 31 Jan 2019, at 09:24, Denis Gervalle <[email protected]> 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 <[email protected]>, wrote:
On 30 Jan 2019, at 18:09, Marius Dumitru Florea <
[email protected]> 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 <[email protected]>
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 <[email protected]> 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 >
Hi Denis,
On 31 Jan 2019, at 09:24, Denis Gervalle <[email protected]> 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 <[email protected]>, wrote:
On 30 Jan 2019, at 18:09, Marius Dumitru Florea <[email protected]> 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 <[email protected]> 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 <[email protected]> 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
Hide devs, From this ongoing discussion, I see the following points being discussed: * Problem 1: Quality of individual change doc in the RN, especially for developers ones. * Problem 2: Cost of creating the RN vs real need and what would be enough. For a given doc budget how do we spend it (more time documenting each individual RN and focus on important ones, or less time per individual RN but be exhaustive). * Problem 3: Java Developer API RN changes vs Scripting users (ie inside wiki pages) * Problem 4: Missing links to reference documentation in individual changes Problem 1 ======== I feel on the issue is that by mandating that every single change be documented in the RN, this lowers the quality of the RN and leads to some changes to be badly documented. It’s not the only reason but I think it makes it harder to provide good RN. I see this similar to Javadoc and mandating that every public method be documented. In a lot of cases the javadoc is very poor. I see 2 solutions: * Solution 1: Apply the current solution but do a better job: It’s already the responsibility of the RM to check the RN and validate it for quality. I often rewrite RN changes even when I’m not the RM but I feel several RMs don’t do this (FTR this is the line "Ensure that the Release Notes are complete and nice-looking for version XXX” in the release plan. ** When checking developer changes, the RM should check that the doc contains usage examples. * Solution 2: Don’t try to be 100% comprehensive for all changes and focus on the important ones. The less important ones are IMO the developer-related ones and especially the Java-developer-oriented ones (hence my original post in this thread). Important point: we must document everything in the reference documentation and thus a link to the reference doc could be enough. Problem 2 ======== We could of course decide to document everything and do it well but it has a cost. It means less time to fix bugs and develop the software but also less time to better document each RN changes. For me the main target of the RN are the users of XWiki. I agree it’s nice to also document the developer API changes but I see that as overdoing it a bit and moving the RN doc to the next level. Seen our team size and that we don’t have any technical writer, I was thinking that we could drop the Java-API changes from the RN, especially since we doc them in the reference doc. Now, we could also argue that if we document them in the ref doc, then it doesn’t cost that much more to add them in the RN too. * Solution 1: Continue as we’re doing but write better developer-oriented changes which means increasing a bit more the RN cost. * Solution 2: For Java-API changes, simply link to the reference doc. Would cost slightly less. Problem 3 ======== Right now we mix Java API changes with Scripting API changes in the Developer section of the RNs. However, the audience might be different. The Java API changes are mostly important to XWiki developers (or anyone developing on the XWiki platform), while the scripting apis are interesting for advanced users of XWiki. * Solution 1: Don’t change anything. * Solution 2: Only doc the Scripting API changes in the RN, see Problem 1/Solution 2 above. * Solution 3: Split the Developer category into 2 Problem 4 ======== * Solution 1: Add a new xproperty in the Change class for the reference doc link and add validation for it. Find how to display it depending on the RN layout used (Grid, etc). See https://jira.xwiki.org/browse/RN-46 Conclusion ========= From what I understand from the current thread discussions, devs prefer: * Problem 1: Solution 1 * Problem 2: Solution 1 * Problem 3: Solution 1 * Problem 4: Solution 1 Is that so? Thanks -Vincent
On 25 Jan 2019, at 09:31, Vincent Massol <[email protected]> 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
participants (6)
-
Denis Gervalle -
Ecaterina Moraru (Valica) -
Eduard Moraru -
Marius Dumitru Florea -
Simon Urli -
Vincent Massol