“It Starts with an Idea” is finally published and available on Amazon – Click here.
Read about the adventure of a start-up in Silicon Valley. The book interlaces the story of the start-up Intelic (renamed “Azerity” in 2001) with stories from prior jobs, valuable lessons learned. The book reveals how Intelic created a dedicated and enthusiastic team – a team that worked hard and had fun – and a great product.
Draft copy of “Practical Software” being reviewed! (UPDATE: We changed the name to “It Starts With an Idea” before publication)
My answer is “yes” but not the old type of Business Requirements Document (BRD). I think there is a role for a new type of on-line BRD – one that can easily evolve during the project. Some argue that TDD is replacing this need. But I think there’s a place in the Agile process for capturing the business requirements/information in parallel with the development tasks that ends up on-line and useful/readable by all. It happens DURING the process, NOT up-front.
I think anyone who believes in Agile knows that the biggest problem with a big fixed documentation up-front, especially in Word, is that it gets out-of-date quickly and then is just a pile of often-misleading words. OR it’s held as the “bible” and then people become possessive of it and build some big process about how to any requirements mismatches, design flaws, etc. become change request-type issues and there we go – Waterfall all over again.
I believe the BAs/PMs are more likely to feel they can retain project oversight if there’s an on-line tool to track the product backlog (in high-level terms) and bring forward when time to implement it and where you can expand/refactor/capture details as you go along. Where stories can evolve into an on-line knowledgebase/repository that people (like the Call Center, Services group, new hires) can read and reference.
Of course, all projects, Agile or not, have requirements that are (hopefully) based on business needs. Some teams are struggling with their PM/BAs wanting to create a large document at the beginning of the project containing detailed use cases with every possible variation on every requirement. Some are having trouble convincing the PMs/BAs that a Product Backlog with user stories instead of fully documented use cases is a suitable method, with detailed analysis taking place during a sprint.
I think the hesitancy from BAs/PMs is a feeling of a loss of control when they are told to just write down “I want this …” stories, put notes on a board and work “in the air” (verbal communication mainly, not written). Some may argue that is a “lack of trust” – but I argue that PMs are also builders/designers who want to end up with “their” product at the end, their BRD. That still can be a valuable artifact. As long as it’s something that evolves with the product seamlessly and isn’t a wall blocking the project.
That’s where Software 2020 fits in beautifully. The prior blog, “Automatic Documentation – How we use Software 2020 to build Software 2020” describes the automatic way to use Software 2020 for tracking tasks, communicating between the team members (PMs and Developers) resulting in both an outstanding product and nice on-line knowledge base repository (aka BRD).
Software 2020 provides rich text online storage that is:
You might think I’m obsessed with having good specs and system documentation. I’ve blogged about it enough. I’d answer that it’s not an “obsession” but that it just makes good business sense. Even stronger than that – I do not think most software companies can operate effectively without on-line access to the final requirements specification.
I’m not referring to User Guides or System Administration Guides that can written by tech writers after the software is complete by using the software itself. I’m talking about the specs that capture the business requirements behind what the code does including all of the possible business variations and configurations that needed to be coded for. That documentation is very tough to write after-the-fact, especially if the code is complex and has a lot of parameters, switches and properties to support different customer configurations and business uses.
We developed Software 2020 to fill this void, solve this need. Before Software 2020 we did it with DOORs Requirements Management System and our internal SD Tracker plus a lot of manual effort and manual linkages. But it was worth it even then.
Good specs are living, breathing documents. Good specs are part of the software process, where the entire team takes ownership and responsibility for their accuracy. That doesn’t mean that there is added work, rather that when used for reference (by anyone – the call center, developers, testers) if the code doesn’t match the spec, a task is created to resolve that mismatch.
A YouTube video is circulating: How to Get to Mars. Very Cool!. It reminded me of the joy of my early years working for Ford Aerospace with satellites and satellite designers. Such fun.
 |
| Intelsat 5 |
At one point in my aerospace career, I was the project lead managing the Ford Graphics CAD/CAM systems. These were big stroke graphics tubes Ford Motor used for designing cars. Ford Aerospace wanted to see if they would be as productive for the satellite designers. The Ford Graphics tubes were as precise as designer drafts. Unlike raster graphic terminals, they used unique vector graphics.
Looking at this Mars video I remember one great designer, John Giassi, who described the technical difficulty of designing the stow point hinges required in order to fold up the satellite antennas and solar arrays so they would fit inside the launch envelop in the rocket cone.
 |
 |
| Intelsat 4A being Designed and Built | |
The hinge had to be done correctly. Once a hinge wasn’t designed quite right so the mechanic on-site had to push it physically to get it in it’s final position. In orbit the array wouldn’t unfold, couldn’t stabilize, and it wobbled off orbit into space. Not good after 3 years and $3 million dollars investment (and that was 1980’s costs)! Using the Ford Graphics system, a stow point error in the Intelsat VA Satellite was found and resolved on the “drawing board” prior to fabrication.
Looking at the video amazes me at the design that has to go into the mechanics to unfold a system as complex as the Mars Rover!
The other story this video reminds me of is one that was told by the Ford Satellite designers about an early rover built by a competitor. 
The rover successfully landed on the moon and carried out mission after mission. Each new mission was designed by the ground scientists based on previous tests and findings and would be uploaded into a special area of memory for missions.
Unfortunately, the concepts grew and the scientists eventually designed a mission that was too large to fit in the memory allocated. They scrambled to find a way to carry out this next important mission. The designers looked through the rover’s specifications and finally one bright engineer said “Aha! We can reuse the memory where the landing coordinates are stored. We’ve already landed so we don’t need those any longer.” Excitedly they went to work. When ready, the new program was updated and stored in memory.
At that point the lunar went dark. No transmissions. What happened? The team went into panic mode trying to find out.
The answer was simple. There was one other function the landing coordinates were used for – an undocumented function. The coordinates were used to let the lunar know where earth was, where to point it’s antenna for communication. Once the memory was overwritten, the rover pointed it’s antenna to some unknown point in space, forever awaiting its next mission.
Guess no one thought anyone would be writing to memory not allocated for missions!
If you liked this post and the video, check out No Ordinary Moments, my reflections about our trip to see the launch of a satellite and the excitement of the young entrepreneurs who were counting on it for their start-up’s future. And if you want to know how to document easily, automatically in an Agile or non-Agile software world, see Automatic Documentation – How we use Software 2020 to Build Software 2020.
To better describe how Software 2020 can help you create your As-Built documents as a by-product of your software development process, automatically, here’s how we used it when we built Software 2020. Of course we couldn’t use it from start-to-finish like we recommend you use it because it wasn’t built yet ☺ But we proved how great a tool it is and will continue to use it as the product evolves.
I first wrote a spec to capture my thoughts and ideas since there was no Software 2020 to put my ideas in but we used it as a guide, not as firm requirements. Freeman is so creative that when he doesn’t need to follow a spec exactly we get better products. Similar to why Agile proposes fuzzy stories which evolve into the final firm specification. We work best as a team when we can iterate and evolve the product as we go along. We’re agile.
So we started fuzzy (like you would with Agile stories). I want a “Task Tracker” tool like our prior SD Tracker (proprietary) tool. I want another document-type, Word-like “view” of the subset of tasks that were requirements or “specs”.
I’ve built enterprise application software for years and managed those efforts, using a combination of tools and proven processes that allowed us to build products quicker, better, and with less people than other software companies could in our field. Our techniques and approaches have withstood the test of time. I knew how I’d like one tool to solve the holes and issues I’m seeing in how companies use tools today: Agile Story Managers, Task Trackers, Requirements Management Tools – and definitely better than what is used in Agile teams that don’t like tools: Word, Excel, Story Boards. I had a good idea of what I wanted. Freeman had great ideas about the new kind of architecture he wanted to build.
The Tracker module was completed first since we had a clear starting place, improving the SD Tracker tool we built at our prior company. We started our project in October and by December the Tracker module was functional enough to use it to enter all of the development tasks in. I took the list of spec/tasks we’d been working from and entered them in the Tracker and from then on we worked as we always have in the past: Nothing gets coded unless there’s a Tracker Task for it and the task is assigned “open-fix” for development, set “in-progress” when work begins, “resolved” when on our integration system ready to test and “closed” when I’ve tested it.
Since by this point were already screens built for the Tracker, we started working to make sure those matched my ‘ideas’ and had some minor corrections. For example, the first task I entered in the Tracker, #1001, was a clean-up task:
As we did the clean-up, we evolved this task to capture the final requirement for screens in the Description of the task:
“There are three types of screens: Summary Screens that present batched sets of information, Detail Screens (Task, Person, Client), and Pop-Ups (attach a New Attachment, Set Defaults, etc.)
“On all screens, in the white top banner, there’s the Software 2020 log on the left and Navigation (Nav) buttons on the right. The first Nav link goes to the user’s Profile. The user’s name should be shown as ” Profile” in the tab bar. That way tech support knows who the user is but the screen is cleaner.
“Below the white banner is a blue Title Bar. The Title should be white and centered in the blue title bar.”
Once we had an “Organize View” feature in February 2012, I selected tasks that represented requirements, like the one above, #1001, and linked them to the appropriate spec until all tasks that represented requirements were in organized specs, by module. Here’s the current Software 2020 Spec List:
Or closer up view:
When I drill into the Look & Feel spec I see this:
Note that it looks like a nice word document (embedded graphics, etc.). That first task, #1001 is there. If you look at the entire screen you can view task information to the right so it’s not just a Word Doc but is a nice way to view, and update spec tasks:
Now I have all of the information about what was built, each and every task, in a nice readable set of specs. This is so much easier and better than trying to maintain a separate Word document or even update requirements in a linked tool. And definitely an advantage over having no documentation at the end except your pile of yellow stickies and code, regardless of how well commented and structured the code is.
Some advocate the Test Driven Development (TDD) approach. I agree there is benefit to TDD and would like to have a Test View on the same set of completed tasks to create test plans from. But disagree that TDD alone would replace real business-oriented requirements specs.
There’s a “Download” button if you want to save versions as Word docs, Excel spreadsheets, or an HTML page that you could store on a central server after each release to have a set of documents reflecting exactly how that version was built.
Then, as the Product Owner, I can add new features for the next release as Stories or requirements right in the Organize View (which is how I like to do it because it’s organized and logical, like a spec or word document) and they show up as tasks in the tracker. I could also, for new features entirely, create a Story Spec and put Themes / Epics / and Stories there.
New spec tasks and any other tasks (bug fixes, maintenance tasks, etc.) assigned to a release can have Story Points or time estimates entered and can be easily prioritized using the Ranking Tool:
Once ranked, the team can assign to Sprints and there’s no re-entering of tasks needed, no extra work.
Prior to Software 2020, we spent 10 years developing robust, secure enterprise application software using the prior SD Tracker tool and the Teleogic/IBM/DOORs Requirements Management System. Our software competed with the big guys – Siebel, Salesforce, SAP, Oracle – and won. Our process and toolset worked effectively but had manual steps and we didn’t have Agile story management tools.
Using Software 2020, the “One Tool” to do it all, is so much cleaner, easier, more efficient, and because of the automatic linkage, clearer for the developers than having to use a tracker then open a requirements spec, look for the links, etc. The task has the link to the spec – one click and they see this task in context with other related information (tasks related to the same function, screen shots, etc.)
For Agile teams, for the first project you would enter Stories grouped under Themes and Epics in the Organize View. Software 2020 provides nice Agile story management tools (charts, ranking tool, story point calculator) to help organize the sprints. As the story evolves, if the PO simply keeps the task/story description up-to-date, and, because it IS the task the developer is working on, there’s no mis-understanding. Because that description is on the task the developer is working on, both the PO and developer can easily view/agree that the description does match the code. There isn’t a separate “Requirements Spec” to maintain. Nothing to get out-of-sync. It’s automatic.
With Software 2020, the company obtains the benefits of having good systems documentation without any added work.
See how our new tool, Software 2020, can produce automatic documentation as part of the project.
(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.
I posted an Agile LinkedIn discussion group question Where do you go to see what the code really does besides asking a developer to start a discussion about the role of specifications in the new Agile methodology. The discussion threads have been interesting and lively (LinkedIn, group “Agile”). So I wanted to answer the question posed numerous times: “Who would use that documentation and why/how?”
First, I’m not talking about old, antiquated waterfall design specs that are soon out-of-date used by no one. I’m talking about living, breathing hierarchical information (in a central tool accessible by everyone) that represent the repository of product knowledge: protected, validated, for use by the entire organization. Documents that everyone in the organization takes ownership in and uses. A cool set of “shiny docs”.
I can answer later how it could have been done (seems it’s not done at most companies and recent surveys say 83% of companies at best use Word Docs to describe their requirements) – but for argument’s sake, trust and believe there is a repository on-line specifications (“shiny docs”).
Who uses our current on-line specs and why do they need them?
a) For the developers – for the new guy, not as a replacement for training and not a static user manual – rather a handy reference area to delve into for more detailed, complex functional understanding, even some design details. A wiki for the product, helpful even for the most experienced developers.
b) Technical Support (TS) (the Call Center) wants to be able to quickly identify if a customer request is a bug, training issue, or if it should become a new feature request. They do their initial investigation using the specifications and replicate the issue in-house if they believe it’s a bug (so they help identify if it’s a customer config problem or base code). For non-bugs, they use them to understand how the product was designed versus what the customer is requesting to give better feedback to the PMs and better represent the customer’s business position for the change versus what’s there. Having a knowledgeable TS team that can get accurate information about all features in a very large enterprise application streamlines getting real bugs and issues into the product development releases. It’s much quicker if everyone knows/agrees a fix is needed than if something just sits on the backlog pile until the next PM release review cycle. Customer satisfaction is improved with clear feedback about if a ‘fix’ is feasible and how quickly. Some product changes can’t be immediate. Customers get that. Clear communication either way improves customer satisfaction.
c) The Product Management Team: If you are a Product Manager for a huge enterprise application and need to add new features and functions requested by customers to an older module with tons of business functionality, you probably don’t know everything about what the product does or even all of the history about what it should do and why customers wanted it that way. The online specifications help immensely.
If such documentation could be produced automatically as the result of the development process – wouldn’t it be useful? Why not aim for that?
(Posted to Duck Pond from Software 2020)
Aren’t new enhancement requests, stories, bugs, and requirements all just “Tasks”? And instead of all the different tools today — Agile Project Backlog Management Tools, Bug Tracker Tools, Requirements Management Tools — shouldn’t those be just different views to manage these (or subsets of these) “Tasks”? I think so.
Story Boards, Requirements Specs, Bug Tracking Tools are all just different views of “Tasks”.
Given that perspective, a modern robust Tracker would manage all “Tasks” (whether they are the new Agile Stories, bugs, client issues, etc.) consolidated for team tracking and estimation to complete reports considering the team’s vacation calendar and all of their work combined.
Then modern Agile tools could help plan new releases taking into account information about the developers’ other work (hence their percent availability) and provide a better estimate of completion for the current sprints and releases. Useful tools then would help manage the current release (in Agile, that’s Story Boards and organized hierarchical views – grouping tasks into epics, stories and their children). And facilitate the team’s management of these Tasks as they move from concept to delivery.
But keep them in the bigger database of “Tasks” so managers can manage the team’s full effort, not just the current release.
That’s what Software 2020 does.
What I worry about are where are the final documents that describe what the software does? That seems to get lost in Agile. And is sooooo important for long term maintenance, Technical Support/Call Center and years later Product Owner updates.
Today documentation is “Not Agile” and I question that. Before Agile if you had a real requirements management tool (we used DOORs) there were requirements, developers would look at the DOORs specs (linked to our internal task tracker for any new feature), during development they’d give feedback if they needed DOORs to be updated (it was fast, real-time, agile), QA would test against the tracker and DOORs and we then knew the DOORs specs accurately reflected what the code did. What a timesaver for Tech Support (the Call Center), PMs and others to know what’s in the code without having to go back to the developer. Without specs you seem to loose that.
Not the waterfall design docs Agile eschews that are in Word and get out of date before the code is delivered – but real information somewhere like in DOORs that says what the product is doing. Information the developers worked from and that QA says is how the code works.
So while I’m totally on-board with the Agile concepts for the software development itself, what is the answer for the rest of the company to know what’s in the code? Are we back to having to have the software developers go look at the code and tell them? Stories in tools like Rally are for the current release. And Agile doesn’t say how to update them or what happens for the next release. Agile “Stories” are incremental. After two or three releases, where does someone go look to see what the code does – other than asking developers? (which is a waste of their time).
That’s one of the big problems we’re hoping to solve or facilitate with Software 2020.
Jan McCleery - from the Duck Pond 