I just read an interesting document on software disclaimers by Jarek Zylinski which is, in short, more of an appeal to develop software using educated (read professionally trained) and ethical (read decent-human-beings) personnel.
I took a few minutes to ponder on the impact this kind of thinking could have to so-called intermediate software artefacts/products created during a product's SLDC.
In today's multi-company development environments, this is especially important as experts from one company might create an overall architecture, while experts from another firm create high-level designs and integration specifications and another firm might actually realize the design into a tangible code. During this process, there are several software artefacts, especially documents, to be generated before the final product is realized, and at some level all of these artefacts could benefit from having a way of telling the audience what they are really about and what the audience should really focus on without getting caught up in the "letter" of the document.
You, as a producer of an artefact that is in the form of a document, need to have a way to declare upfront where you've directed your efforts and your wishes to ensure that the audience views the document as you do.
Here is, what I believe to be one of the clearest disclaimers to add to a technical document:
I took a few minutes to ponder on the impact this kind of thinking could have to so-called intermediate software artefacts/products created during a product's SLDC.
In today's multi-company development environments, this is especially important as experts from one company might create an overall architecture, while experts from another firm create high-level designs and integration specifications and another firm might actually realize the design into a tangible code. During this process, there are several software artefacts, especially documents, to be generated before the final product is realized, and at some level all of these artefacts could benefit from having a way of telling the audience what they are really about and what the audience should really focus on without getting caught up in the "letter" of the document.
You, as a producer of an artefact that is in the form of a document, need to have a way to declare upfront where you've directed your efforts and your wishes to ensure that the audience views the document as you do.
Here is, what I believe to be one of the clearest disclaimers to add to a technical document:
The contents of this document are believed to be accurate. This is not a legal document and should not be treated as such. The statements, information and recommendations mentioned in this document are intended to be read more in spirit than in letter. This document is intended to be objective. Any subjectivity or bias that has crept into this document must be considered unintentional and must be attributed to a human failing on the part of the author. The author(s) of this document agree to the terms above. |
I really don't recall where I got this from, but I do recall seeing something similar in a document I read on the internet. I might have, at the time edited it for relevance to my field of work but have lost the source of this inspiration.
0 comments:
Post a Comment