Document update notification in the release notes.

  • 3
  • Idea
  • Updated 2 years ago
I like having the latest version of SSDR software installed and I also try to keep a paper copy of the latest Software and Hardware Manuals. It would be very nice if the Version Notes had a little section that specified any documentation changes that have been made. I don't mean details, but maybe a list of sections, or pages or, at least which manuals have changes. Just a one liner would do (i.e. "Documentation changes have been made in the SSDR Software User Guide"). It could even be a check off box for each manual. I'm from the old school and like to read off a paper page rather than a computer screen so I keep my printer very busy. Just a suggestion.
Al,  N4AB
Photo of Al

Al

  • 160 Posts
  • 9 Reply Likes

Posted 2 years ago

  • 3
Photo of Rick

Rick

  • 158 Posts
  • 20 Reply Likes
Excellent suggestion especially considering the frequency of updates
Photo of Martin Ewing AA6E

Martin Ewing AA6E

  • 252 Posts
  • 52 Reply Likes
Yes, some attention to how documentation updates are handled would be good.  In theory, to have an up-to-date copy, you have to download all new files for every release.  If you want hardcopy, it's quite a big job to print and manage all that paper.  (I priced it at $50 or so at the local quick copy place, if you want it nicely bound.)

Since a large percentage of the docs is unchanged between releases, it would be VERY good if there was an incremental doco update process.  In the good old days, vendors would send out revisions of just the pages that had changes on them, for us to insert in our 3-ring binders.  Of course then we complained how much trouble it was to replace all those pages...
Photo of KM4CQG

KM4CQG

  • 218 Posts
  • 32 Reply Likes
They already do this guys if you simply read the Release notes.

SmartSDR v1.9.13 Release Notes

Ian
Photo of Al

Al

  • 160 Posts
  • 9 Reply Likes
Where does Flex put that info in the notes, I guess I'm missing it.
Al, N4AB
Photo of KM4CQG

KM4CQG

  • 218 Posts
  • 32 Reply Likes
Go to the flex radio website, click on top right 'support' and select 'downloads' and it's right
there under 'smart SDR' and 'Documentation'

Ian
Photo of Al

Al

  • 160 Posts
  • 9 Reply Likes
Ian
I know where the Release Note can be found, what I can not find is any reference to a change in the SSDR documents. That is what I was referring to.
Al,  N4AB
Photo of NX6D Dave

NX6D Dave

  • 273 Posts
  • 70 Reply Likes
Thanks for these suggestions, I'll keep them in mind.  I help FRS with the documentation and am usually the person who handles the documentation sources just before they go to Tim for publication on the web.

I've considered change bars in the documents, but so far the idea has not worked out.  When changes are put into the documents to follow changes in the software, I frequently also work on the formatting and layout of the text as well.  This can cause widespread but minor changes throughout, putting change bars on a large number of pages that didn't have material changes.  With more effort it may be possible to limit the change bars to the proper pages.

We've recently moved the documentation source files to a well organized GIT repository and are now tagging that repo when we release a set of documents.  Because of this, it is no longer useful to us to have a "Version History" page in the docs.  In coming releases, it will be removed.  The document versions will be clearly labeled with the version of the software they represent, as they are now.

One problem with change bars and printing is that if you attempt to print only changed pages you can wind up with a mess since sections may move and change length, pages may be inserted or removed.  This changes the page numbering and hence the Table of Contents.  Back when technical documentation was sometimes loose leaf and change packets were distributed (Yes, I remember this time) it was also common to wind up with documents with no page numbering, or numbers like "17-a, 17-b then 17-e".

In FRS documentation, it is very common for new sections to be added to a document like the SmartSDR User Guide.  This is usually the result of the addition of a feature to the software.  These insertions usually cause a number of pages after the insertion to change format and for all of the pages after the insertion to change number.  The simple fact of the matter is that modern document preparation systems don't really want to support the idea of change sets.

Nevertheless, I'll see if change bars can be made useful.  We'll have another round of document updates before long.
Photo of KY6LA - Howard

KY6LA - Howard, Elmer

  • 3403 Posts
  • 1292 Reply Likes
As one who was thrilled with the demise of paper documentation and the end of paper updates

PLEASE DO NOT CLUTTER UP THE EASY TO READ ELECTRONIC DOCUMENTS WITH CHANGE BARS AND OTHER SUCH DISTRACTIONS.
Photo of Ken - NM9P

Ken - NM9P, Elmer

  • 3823 Posts
  • 1164 Reply Likes
I would agree, with an addition....

The downloadable manuals should be complete and up-to-date at all times.  
When a new version is released, and the online manual is updated, then there should be a page or more that highlight the major changes with descriptions of how the software may function differently from previous versions.  This is similar to release notes, but a little more detailed and tutorial for the sake of those who may need concrete examples in order to understand the changes made since the previous version.

This would be helpful, without needlessly cluttering up the standard documentation.

Ken - NM9P
Photo of Martin Ewing AA6E

Martin Ewing AA6E

  • 252 Posts
  • 52 Reply Likes
Dave

Thanks for the insight into the documentation question.

Maybe it's hopeless to think of keeping up to date hardcopy on the shelf. Lots of us OTs are still geared to paper and "real" instruction books, but we can adjust!

But why not be really modern and go to responsive web-style pages? The docs are currently formatted for the 8 1/2 x 11 page and then PDF'd. If we're not going to print them, maybe the format doesn't make sense. Many of us would like to read on tablets or phones via an app or browser, without too much pan and scroll.

Responsive formatting can be tough for tables or graphics, I know. But you'd come up with something...

Keep up the good work!

Martin AA6E
Photo of Kevin K4VD, Elroy

Kevin K4VD, Elroy

  • 775 Posts
  • 170 Reply Likes
The nice thing about PDF is that it is easy to store and recall. I keep a lot of my documents on Google Drive. I also have a copy of some of them on my phone, tablet and laptop (HT, car rig). It is much easier to read them in PDF format especially if a network connection isn't currently available.

The other thing I do with PDF files is highlight passages and make notes. That's something that's probably not easy to do with a web site.

I could probably go either way but I'd like to keep a PDF option. I think some html documentation tools can create PDF on the fly?

As for cluttering up a document, I'm ok with a good "Changes" section but I actually like bars along the side. I can't see how that would be any more distracting than menu bars, icons, tabs or links scattered all over a window already.

Going from an old version of a document to a new version and knowing where to look for the changes is both a time saver and a mistake saver.