Features and the behavior of the product should be documented. The PM, QA, Marketing, Sales, and Docs teams all need to understand how the product behaves without being overburdened by too much detail. Even for developers, it’s nice to have a reference and overview of how a feature works. Most requirements docs I have seen are horribly over-complicated, include too much detail, cross-reference JIRA tickets, cross-reference QA test cases, and are often incomplete, dated, or just plain wrong. The cross references are bad because they are almost always incomplete. The documentation becomes incomplete, dated, and wrong because it is complicated and/or the procedure to update the documents and have them approved is too process intensive. In short order, the whole effort becomes a waste of time. Thus, let me introduce you to axioms.
To resolve the issue, 1) documentation must be simple, 2) it must be easy to update and maintain, 3) it must convey the necessary information. I have found what I call axioms to be a good compromise to the problem described. So, what is an axiom? An axiom is a simple truth. It is a statement of how a feature behaves. No flow charts, no graphs, just a statement. For example, “Processing a database that does not match the engine’s version will result in deletion and regeneration of the database from the original contents”. Axioms assume general knowledge of the product. Axioms provide sufficient information for the QA team to produce tests. Any feature self evident when using the product is not included in the list of axioms. For example, if there is a button in the UI called “print document”, there need not be an axiom stating “the product should provide a button that allows the user to print the document”. Avoiding self evident items keeps the axioms from being cluttered. Another example is “The ‘go’ button shall be colored blue”. There is no reason to document this as a feature. If the ‘go’ button changes to green, almost always the color was changed by design. Again, the reason to avoid such axioms is to prevent clutter. So yes, the addition of axioms is subjective with the rule “self evident axioms are not documented”. Axioms should be stored in a wiki that is easily accessible and editable by everyone, in which people can receive notifications when updates occur, which maintains a revision history, and is searchable. An alternative to a wiki are simple .txt files in a central repository or under source control, though this is less ideal. Whatever you do, don’t put them in a Word document or other difficult-to-access object. One addition to axioms that may be done is tagging each axiom with a version so readers know when features were introduced into the product. To produce axioms the first time without too much effort, simply tag these as “legacy” or “<= v12” if the current release is version 12. The key point is to keep the procedure simple.
I have yet to see a non-mission-critical company be able to keep accurate, up to date requirements. As such, I like to use axioms. The key behind axioms is to keep the process simple otherwise the documentation will soon become a waste of time as it loses value due to inaccuracies. It should take an engineer seconds to make changes and an axiom should only be created if it is self evident to avoid clutter. Overall, axioms provide a nice compromise between not having requirements at all and having an overly burdensome process to create requirements.