> 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/
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
>
