Release Notes comments/questions

[sdcinvan]

v11 release notes are here: http://kb.madcapsoftware.com/#Flare/Gen ... tes|_____1

Questions:
1) Why doesn't MadCap include "known issues" in the release notes? This list appears to be what is corrected.
2) The new v11 features state that git is supported but why don't the v11 release notes mention git. Additionally, is git ssh supported?
3) Likewise for ePub... significant enhancements have been made but the release notes do not describe most of the enhancements.
4) Where are the release notes for Analyzer v8 and Contributor v7 ?

BTW...
I find your release notes formatting rather difficult to read. The way I do release notes is to include a new features summary, enhancements and fixes (compartmentalized), known issues (at time of version release), and a trouble-shooting section that describes known work-arounds for applicable known issues.

[betelgeuse]

I second sdcinvan's sentiments regarding the formatting of release notes. They are extremely difficult to read. I want to be able to see a list of new features, and a list of fixes.

Matt

[atomdocs]

Well, the summary says that this list contains bug reports and feature requests, and that's what it does. Although, I expect this list is compiled automatically from a ticket system, and some of the entries are not complete. I really just use this list to search for bug tracking numbers to see if my issues have been addressed, and then move on.

For "What's New", MadCap put a lot of effort into producing some really good info on this: a dedicated webpage, a video, and a PDF. It's all here: http://webhelp.madcapsoftware.com/flare ... _Flare.htm

[sdcinvan]

Well, the summary says that this list contains bug reports and feature requests, and that's what it does. Although, I expect this list is compiled automatically from a ticket system, and some of the entries are not complete. I really just use this list to search for bug tracking numbers to see if my issues have been addressed, and then move on.

For "What's New", MadCap put a lot of effort into producing some really good info on this: a dedicated webpage, a video, and a PDF. It's all here: http://webhelp.madcapsoftware.com/flare ... _Flare.htm

I've been building release notes for years and in my opinion, release notes shouldn't be a simple computer generated listing. It needs a human touch to help make sense of what a customer should expect after they upgrade. As I stated yesterday, the release notes fails to mention what the status of the issue list. It is inaccurate to assume that the list represents all items that were fixed or added and we shouldn't assume that the "what's new" document represents everything as well.

The release notes state, "The following is a list of customer-reported issues that were addressed." What about new features or bugs that were discovered by MadCap? Release notes are supposed to include new features, changes to current features, issues that may impacts users, etc.

Some examples:
- You can now pin projects on the start page - it isn't mentioned in the release notes.
- git support was announced as a new feature but it isn't listed in the release notes.
- epub was significantly improved but epub issues are scattered throughout the v11 release notes with no clear indication of how the improvements will impact the end user.
- The number values... what do they represent? Bug reports and/or feature requests? If all, there doesn't seem to be any consolidation because I was issued feature request #81418 (image maps not supported in PDF output). This is now fixed but there is no 81418 in the release notes. There are a dozen other feature requests and bug reports that I was issued, they were addressed in v11 but not included in the release notes.
... and there are many other changes to v11 that are not mentioned in the release notes or in "what's new".

BUT KUDOS to MadCap for introducing v11 with the professionally produced videos and tomorrow's webinar. I don't do that but it is an excellent idea to adopt!

[jjw]

Additionally, is git ssh supported?

I think that's a no.

J

[RossF]

Release notes, always my first pit stop while the application is downloading...

In addition to the above feedback, it would be helpful to have the V11 Beta corrections split out into a second table. Anyone moving from an earlier version simply doesn't need to read them. I do see the value in them for the beta testers though. This was a particularly large list, it made my eyes glaze over

I have had tech support staff get mixed up between bug report and feature request numbers when quoting one at them, so we don't have a hope here

Props for the What's new video.

[wclass]

...
Release notes are supposed to include new features, changes to current features, issues that may impacts users, etc.
...

Who says?
People have many different views on what release notes should be - and where I work we get them all!

We are now pushing for people to stop putting details about new features into release notes, and have them just link to the online help. We had problems because people put all the information in release notes, and so a year or so later, if you want to know how something works you have to remember what release it was in - NO good for newcomers.

I really like Flare's "What's New" section, and a simple list of bugs fixed helps me know if items I've asked for have been fixed or not. Nowadays you just don't need everything in the one document. They probably should contain a list of items that would impact rolling back to the previous version, though.
For the Flare release notes, I'd probably recommend they work on grouping similar items. For example, there are about 5 items relating to importing Word tables with header rows - this should really have been only one item. And some of the Description text could be worded better.

[Nita Beck]

Re the wording of the Descriptions standing improvement: I think many of those were written by us, the users. I definitely recognize at least one of those as mine. Others are probably the techs from called in problems.

[sdcinvan]

Release notes, always my first pit stop while the application is downloading...

In addition to the above feedback, it would be helpful to have the V11 Beta corrections split out into a second table. Anyone moving from an earlier version simply doesn't need to read them. I do see the value in them for the beta testers though. This was a particularly large list, it made my eyes glaze over

Absolutely agree.

I've made 'feature requests' for reformatting the release notes since I first encountered them two years ago. But I'm not the only one who produces excellent release notes... take a look at Mozilla's excellent release notes (for a FREE product). This is an example of both good looking and highly functional: https://www.mozilla.org/en-US/firefox/3 ... easenotes/ There is no excuse for not producing release notes like this. I also looked at a dozen other company's release notes, such as Adobe, Microsoft, VMware, etc... It seems that MadCap might have the worst release notes in the world.

Props for the What's new video.

MadCap does do this very well!

[sdcinvan]

Additionally, is git ssh supported?

I think that's a no.

J

Thanks. Rob replied with a reasonable explanation and that there is a push to get this working as quickly as possible.

[sdcinvan]

...
Release notes are supposed to include new features, changes to current features, issues that may impacts users, etc.
...

Who says?
People have many different views on what release notes should be - and where I work we get them all!

There is a standard convention that most companies follow, not because of any status quo but rather, because it is logical. It is important to include a list of new features, what's been fixed, what behaviors have changed, and include any known issues because it greatly assists the end user to determine impact on his or her environment. I think we all agree that the current MadCap formatting makes any of this easy to determine.
Go ahead... tell me this isn't easier to follow... https://www.mozilla.org/en-US/firefox/3 ... easenotes/

We are now pushing for people to stop putting details about new features into release notes, and have them just link to the online help.

I absolutely agree. Release notes must be as succinct as possible. Again, take a look at the Mozilla release notes example.

...and a simple list of bugs fixed helps me know if items I've asked for have been fixed or not.

That is what the release notes are for. The release notes are responsible for listing all fixed bugs as well as any known bugs that did not get fixed in the release. Again, to help the end user determine impact.

They probably should contain a list of items that would impact rolling back to the previous version, though.

I've never seen that kind of list in release notes but it might be a good idea for some products.

For the Flare release notes, I'd probably recommend they work on grouping similar items. For example, there are about 5 items relating to importing Word tables with header rows - this should really have been only one item. And some of the Description text could be worded better.

Yes, yes, yes! That would be a step in the right direction.

[sdcinvan]

Re the wording of the Descriptions standing improvement: I think many of those were written by us, the users. I definitely recognize at least one of those as mine. Others are probably the techs from called in problems.

They definately use your words but they might be just a little bit reformatted by the one who enters the ticket.

For example, one of mine is, "87363 - Flare crashes when high-bit ASCII characters are copy and pasted into the XML Editor - XML Editor" That is a succinct version of my long-winded, 84 word (not including trace stack) bug report.

I really like how MadCap will email you when your reported bug is fixed. Very nice idea that I have never seen before!