Stream: IG creation
Topic: IGs and Software Documentation
Bob Milius (Jan 09 2019 at 16:15):
I've been asked if it's appropriate to add software documentation to an IG that an organization creates and maintains. My feeling that is that they should be separate. The IG should should give guidance to for developers, but the product of the developers should be in a separate doc. Is that correct?
John Moehrke (Jan 09 2019 at 16:30):
In a perfect world, yes.. but often times an IG does need to give system design hints. (e.g. this data that was just given to you must be preserved as it will be asked for later on a different interface)...
The main reason to keep these out of an IG is to assure that the IG is as portable as possible. That is, the IG is not fixed to a specific type of technology, or technical architecture. An IG should be re-usable in various settings.
BUT, sometimes the audience for an IG is very specific. Such as an IG being written to both define an interface and a persistence systems design. Sometimes it is just most efficient to write it together. Just recognize that when this is done, it will limit the re-usability.
Lloyd McKenzie (Jan 09 2019 at 16:33):
"Should" is a question of context. And the notion of ImplementationGuide is context-independent. We can come up with good/best practices for particular uses of implementation guides, but there will always be legitimate uses that violate those guidelines
Brian Postlethwaite (Jan 20 2019 at 22:36):
We definitely plan to document our server through an IG, which will include links to the other guides/packages that it uses.
Last updated: Apr 12 2022 at 19:14 UTC
