Skip to main content

Reliable form of technical document

Last post 09:30 pm July 5, 2020 by Simon Mayer
3 replies
03:34 pm July 4, 2020

Besides the source code itself, which below are most reliable form of technical document are reliable?

  • Development Team's whiteboard
  • UML model
  • Passing test harness with clear naming
  • Spreadsheet of passing manual test
  • Release notes
  • Help file

 Is that UML model?


03:12 pm July 5, 2020

Which do you think would be of most value in a Definition of Done? Which would provide the best assurance, regarding the quality of the increment, that is most timely and least prone to error? 


08:41 pm July 5, 2020

How do you define "reliable"?

A whiteboard may be a good indicator of what the team wants to do. It could also be used to create a snapshot of a current state at a particular point in time. However, it may be difficult to assert the correctness of the whiteboard. It could also be at various levels of abstraction - it can be reliable to one audience with a particular information need, but not another with a different information need.

A UML model can be reverse-engineered from code. This could be highly reliable at the point in time in which it was generated. However, it can quickly fall out of date if it isn't synchronized with the code. A hand-drawn UML diagram runs into the same problems as a whiteboard with respect to levels of abstraction, the ability to assert correctness, and long-term maintenance.

A passing set of tests says nothing about the quality of the tests. It's pretty easy to write tests that will always pass. You may even have high coverage with low-quality tests. You may also disable or choose not to run tests, which would bring up questions as to why the tests are disabled. Are they failing, indicating a problem with the system under test? Are they flaky and poorly written tests?

A spreadsheet of manual tests is another snapshot in time. It may show what a person tested, how the tests were carried out, and what the result is. However, rerunning those tests later may result in different results. It also says nothing about the quality of the tests against the requirements or expectations of stakeholders.

Release notes can capture a list of changes between two versions of a system. Help files can help a user interact with a system. Ideally, both are correct, but they do require generation and maintenance. They may be incomplete, and failure to maintain them could make them incorrect.

Reliability depends on the context. Who is the intended audience? What is their information need? How often is the information updated and maintained?


09:30 pm July 5, 2020

Have your Development Team expressed a situation that they think would be improved with technical documentation?

What do the Development Team consider the most effective solution that still allows them to deliver sufficiently valuable Increments of the right quality?


By posting on our forums you are agreeing to our Terms of Use.

Please note that the first and last name from your Scrum.org member profile will be displayed next to any topic or comment you post on the forums. For privacy concerns, we cannot allow you to post email addresses. All user-submitted content on our Forums may be subject to deletion if it is found to be in violation of our Terms of Use. Scrum.org does not endorse user-submitted content or the content of links to any third-party websites.

Terms of Use

Scrum.org may, at its discretion, remove any post that it deems unsuitable for these forums. Unsuitable post content includes, but is not limited to, Scrum.org Professional-level assessment questions and answers, profanity, insults, racism or sexually explicit content. Using our forum as a platform for the marketing and solicitation of products or services is also prohibited. Forum members who post content deemed unsuitable by Scrum.org may have their access revoked at any time, without warning. Scrum.org may, but is not obliged to, monitor submissions.