Document update notification in the release notes.

N4AB

Rick

Excellent suggestion especially considering the frequency of updates

Martin AA6E

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

Ian1

They already do this guys if you simply read the Release notes.

SmartSDR v1.9.13 Release Notes

Ian

N4AB

Where does Flex put that info in the notes, I guess I'm missing it. Al, N4AB

Ian1

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

N4AB

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

NX6D Dave

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.

KY6LA_Howard

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.

Ken - NM9P

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

Martin AA6E

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

Kevin

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.