How to Document Software in the 21st Century – “Organize” View

(Copied from Software 2020 Blog)
On a recent LinkedIn post, people were saying “we still struggle … when it comes to testing and documentation” and not having good design documentation “creates difficulty for the software testers to come up with tests …” and that “In regulated environments, documentation is a must … and most important tracing from requirements to design and tests.”

I think you can have both. I believe having traceability from the design specification to tests and ending up with an accurate “As-Built” Spec is a “must” and valuable even in Agile environments. What “isn’t” Agile is expecting everything to be completely designed up-front. Rather I believe in evolving the requirements (or fuzzy up-front stories) but at some point the task must become clear enough for implementing.

My friend and I were VP Engineering and CTO respectively at my software company. She and I had both come out of the Aerospace industry and wanted to take what we’d learned and throw out the unnecessary steps to create a light-weight, high-quality process for start-ups. We called our process “Practical”. People who saw how we worked said we were agile. One key was we integrated an on-line requirements management tool tightly into our process. I’d update the new features in the on-line specs. Some would be complete up-front if the change was well-know and researched. Other times there’d be a placeholder – “We want a configurator”. Developers worked from these on-line specs. We were iterative – sometimes the specs evolved with the prototypes and the inventiveness of the developers but before testing started, the specs had to be finalized. Testers tested against the spec updates. I had a lot of manual work to link tasks to specs and make sure the wording was always up-to-date as the tasks evolved. But well worth it. The whole company leveraged those on-line specs. Extremely valuable.

But I always yearned for a better integrated tool where the story was automatically a task so everything was in one place. And as the task was split, refined it stayed organized, like in a spec so at the end I had accurate, on-line description of the actual deliverable product.

Companies now embracing Agile (completely or some hybrid) start with an Agile Story Manager tool and often need to re-enter tasks into their tracker. In companies that used to have good, integrated specs as part of their process like ours, those specs are becoming inaccurate, aren’t used by developers to code from and aren’t tested. Worthless.

We built Software 2020 because of these needs. It’s the tool I’d always wanted and we’ve been using it to build the tool itself (how’s that for iterative 🙂 There’s an “Organize” view that lets you structure your stories in a word-like doc (you could start with themes and epics but if you had an existing organized view “spec” you’d add the new features in their proper place) with screenshots, etc. and each specification is automatically a developer task. You can update the description of the specification as design is clarified either in the “Organize” view or regular task Tracker screens. Later we want to add another “view” for the test center. That gives the linkage the regulatory projects need – automatically. But even for non-regulatory, even on our little tool-building project, my architect/developer is already finding the value of looking at the document view of my design spec, in-context, to better understand the new features I’m designing/asking for. So I think we can be Agile and have nice documents too.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s