2

I have updated the firmware on my device to accept new commands. How do I make it clear to other developers that the new protocol document is specific to this recent version?

Should I make it clear which commands are reverse compatible in the new protocol doc, or should the other devs be expected to look up the old protocol?

I think putting the applicable firmware version in the title makes the version number seem to apply to the documents itself ie the the read thinks the protocol is at rev 2 instead of apply to rev 2. I also think release notes should be their own doc.

peteey
  • 411
  • 1
  • 4
  • 10

2 Answers2

2

You should make the way for people wanting to update the firmware too. For this

  • people should understand if their developments will work on the new version of firmware. If you just change protocol removing previous version, there's a risk that existing applications will not work, and some people will just dump your device. This point is not about documentation, but about your tech strategy;

  • I would vote for two documents: joint document of the most recent firmware functionality, and release notes which highlight the changes and additions. The size and complexity of these documents depend on the severity of changes to existing API in new firmware.

Of course documents should clearly state which version they are for, when they are released and why. Both documents should be searchable (e.g. PDF searchable with ^F key combination) so that users can easily find words they have in mind.

Anonymous
  • 7,052
  • 1
  • 14
  • 45
1

I recommend exposing a way for application software to interrogate the firmware version for a start at a minimum. As for making docs version-correlated, I am a fan of how node-serialpoet does it. Check out their Github README.

https://github.com/EmergingTechnologyAdvisors/node-serialport

vicatcu
  • 22,695
  • 14
  • 81
  • 156