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