Lessons from the Moon. Gotta have good documentation!

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 Satellite
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 Sketch Intelsat 4A being built
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. Lunar Rover 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.


What not to do on your first job – Don’t Make Assumptions

A college grad arrived on his first day at work to report to his new supervisor, Saul.

Just before he arrived, Saul’s manager, Glenda, went to their admin’s desk and sat down to jot down a note. Just then the college grad arrive with a big smile, eager for his first day.

“Hi,” he said to Glenda. “Is Saul in?”

“Yes, he’s in his office,” she politely responded.

“Would you tell him I’m here?” he asked.

“Sure,” she said smiling. She was going to head past his office on the way to hers.

“I guess you’re the admin, huh?” he said beaming with excitement.

“Actually, no, I’m Saul’s boss.”

The poor kid almost passed out, went ten shades of pale, groaned, stammered. He was sure he was about to be fired on his first day. Glenda just got up, chuckled, and headed back to tell Saul his new hire was here. She kind of liked him.

Do we too often “Assume”?

On a linked in group, a women engineer started a discussion about how she’s tired of the computer science world where men treat her rudely, make inappropriate comments, etc.

One fellow posted a comment. He said he was about to graduate with a BS in Engineering and he wanted to be sure he “treated the girls they way they want to be treated.” Ho boy. Did he get an earful about the proper way to address a “woman”. He was confused. “But you call us ‘guys’, isn’t it OK to call you girls?”

“No,” the answer quickly came back. “Would we call you a ‘boy’? What’s important is equal treatment. If you call yourselves ‘men’, call us ‘women’. If you want to be the ‘guys’, then we can also be part of the ‘guys’ or ‘gals’ but not, not ‘girls’.”

The poor lad was quite concerned. “Gee,” he commented. “I’m not even out of college and already I’m making tons of mistakes.”

“No worries,” they said. “Just pay attention and treat us equal. I’m sure you’ll do OK.”

A Tale of Two Universes (Selling “Vaporware”)

We’ve all heard the term “vaporware.” Software companies are notorious for selling it. It has become such an invasive practice that customers expect it.  

It seems all right at first. The Sales guy has a hot new client. The software “almost fits” their needs. It’s just missing a few fields here and there, a little function over here, one over there. He sits down with a member of the engineering team. “Can you mock up what this would look like?”

“Sure,” says the engineer. “That would be pretty easy to add on.”

“What about this function over there?”

“No problem,” says the eager engineer. He can envision how it would be implemented and it isn’t that large a stretch.

The Sales Rep goes off to his next customer meeting with his “demo” and powerpoint slides in hand.

“See – we understand your business issues, we can take care of your needs.”

The customer debates a bit but three months later, the contract is signed, software purchased.

The Implementation Team has been selected. Before they head over to the customer site, the Services Manager calls the Services Lead into his office. “One thing you should know. The customer thinks the product does this and that and has these functions.”

“What?” says the concerned Services Lead. But it doesn’t!”

“Can’t you just configure it on the outside?”

“It doesn’t work that way! We need some product changes.”

“That’s OK – the engineers said it would be easy.”

The Services Manager goes to the VP of Engineering. “When can we have this product upgrade?”

“Product upgrade? We’re just starting final test right now for our major release. If we put this in now it would delay the release significantly and we have customers who are planning on this schedule.”

“But it’s a ‘must have’ for our new customer. Sales committed to it!”

The Executive Committee has an emergency meeting. Engineering is directed to create a branch in parallel during their final test sprint to try to get these features out right after the main product release, against their policies. The new features will be released 1 month after the major release.

The concerned Services Lead is told that they will just need to “fudge it” for the first few months of the implementation project.  

“It’s OK”, says their Manager. “The customer is using the Waterfall method and are first going to firm up their requirements, then spend a couple of months on detailed design. By then the release will be ready.”

An uncomfortable team heads over to the customer site with their instructions. They had been directed that during requirements review, to pretend that the features are in the product and check off the requirements associated with the new fields and functions as “OOB” (out-of-the-box). “It’s all right”, they are told by their Manager, “because they will be in the product real soon.”

During the detailed design phase the customer starts asking to see the product to help them envision the customization changes they are designing. The Services team knows many of the big features they expect to see there just aren’t there. There’s tap dancing.

Eventually the customer figures out that the software isn’t all there. The truth is out. There is a huge blow-up and the customer calls the CEO to complain. The CEO assures them that their features will be in the new release. They are still upset but sit down with the frazzled Services Lead to iron out what a viable implementation schedule would be including incorporating the upcoming product release. They start their work on the current release for customizations that don’t require the new features.

The new release is delivered and the customer’s policies require a total re-test. While re-testing they uncover minor changes in the completed configuration needed due to the new product enhancements not being exactly how they’d envisioned them. Because of re-testing and re-work, both cost and schedule are impacted. Although the contract was “Time and Materials”, they call the CEO and refuse to pay any extra cost due to re-work and he concedes. Still the project costs them more money than planned due to the schedule impact.

The customer isn’t happy but is used to software companies that are less than truthful. Standard practice, they grumble. The skilled Services team eventually delivers the final solution but the customer is less than thrilled.

Replay in a Parallel Universe

The Sales guy has a hot new client. The software “almost fits” their needs. It’s just missing a few fields here and there, a little function over here, one over there.

  He sits down with a member of the engineering team. “Can you mock up what this would look like?”

“Sure,” says the engineer. “That would be pretty easy to add on.”

“What about this function over there?”

“No problem,” says the eager engineer. He can envision how it would be implemented and it isn’t that large a stretch.

The Sales Rep sits down with the Engineering Manager. Here’s the features and functions that Client X will need if they buy the product. Is it feasible to get them into the current release?

The Engineering Manager and Product Manager have a quick meeting to determine the feasibility. They will need to move some features out of the current release now to make it happen but there are no clients waiting for those. She gets back to the Sales Rep with an “OK – as long as the customer can commit within the next few weeks while we still have a few Sprints left.”

The Sales Rep goes off to his next customer meeting with his “demo” and powerpoint slides in hand.

“See – we understand your business issues, we can take care of your needs. These few functions are not in the software yet, but if you buy the product the Engineering Management team has agreed to provide them in the next release which will meet your schedule. If you can sign the contract this month.”

The contract is quickly signed, software purchased.

The Implementation Team has been selected. During their internal kick-off meeting, before they head over to the customer site, the Services Manager calls the team into his office. “One thing you should all be aware of. There are a few features that are missing from the product but engineering has already agreed to deliver them in the upcoming release which meets the customer’s schedule. The Product Manager will work with your team and your customer to make sure we build the features the customer is anticipating.”

“Great.” says the Services Lead.

During the detailed design phase they start reviewing the product and proposed changes. The customer can provide input into the new features and iteratively they improve on them before the product development team has started their coding. In fact, they find a way that the product changes can be implemented that remove some of the customizations that had been bid, saving the customer implementation money.

The project is completed on-time. The customer feels they are part of the team and the vendor is the best vendor they’ve ever worked with. They will definitely consider this vendor for their next project.

They are happy to give a Press Release and authorize a marketing blurb for the vendor’s website.

Why Sell Vaporware?

Why do software companies feel they need to sell vaporware? Some misguided notion that customers won’t buy a product unless it has all features today?

The second scenario brings everyone on-board. The company is collaborating. The customer is respected.

Having worked on projects sold both ways, I can attest that the second, honest and up-front scenario is by far the best.

Story of a “Successful” Off-Shoring Experience

“Software Companies need an Off-Shoring Strategy”
(or so they were saying)

In the start-up I co-founded, our CEO (and my partner) was pushing hard for an off-shoring strategy. This was the late ’90s/early 2000’s and the buzz in the software business was that the way to grow quickly and cheaply was using the Indian offshore companies. He would regularly send me emails saying “5 skilled programmers for $15/hour” whereas compared to the rates we were paying was a significant reduction. Reading further, there were additional management costs but but still seemed impressive. In addition, this was still during the dot.com boom and local talent was hard to find. (I’d remedied our lack of hires by partnering with a local Indian contracting firm who was providing us with developers where the contracting firm held their H-1 Visas).


I felt inherently that it would be difficult to build a team off-shore but had no concrete reasons for my reluctance so I attended a couple of seminars around offshoring.

  • Many presenters gave facts and figures on the great cost savings. The Indian consulting firms described how cheaply they could provide CMMI Level 5 qualified work. (Since in my early years I was involved in the development and use of SEI Assessments, the predecessor of CMMI, I seriously doubted their Level 5 claims and believe it was more like ISO 9000 where everyone is trained about the steps – how to check in code, how to do code reviews – but not that the development and quality is superior).

  • The large software firms spoke highly of their cost savings. Most had large facilities they owned, operated, and managed where they sent software for final testing or had customer support centers.

  • One presenter discussed how to set up your own facility in India which included numerous lengthy trips to India and the mandatory bribes and dinners with various officials in order to get anything done.

  • Another presentation covered how to set up a “lease-to-buy” program in India, where you’d partner with an Indian firm who would set up a facility, hire resources including management, work with you to train them with the goal of transferring the facility and resources to become employees of the company. That sounded the best but still involved a great deal of up-front negotiations and travel. Until the team is turned-over to your company, there is an overhead fee paid to the services company including equipment and facility costs plus service company fees.

  • I met one person from a small company who swore that offshoring was the way to go. Digging deeper I found that the product expert for their company was located in Russia and he had hired, trained, and was managed their offshore development team from the company’s inception. Their main difficulty was how to train the U.S. Sales and Marketing people but solved it by having Sales and Marketing travel to Russia periodically. An entirely different situation than I was faced with.

  • All presenters from small-to-mid-size companies discussed the high turn-over rates and large yearly increases the region was currently experiencing due to the big corporations, like Oracle, that paid more and that Indian engineers felt gave them better prestige.

  • In addition, the presenters all had similar statistics regarding the number of managers needed per developer, additional cost for up-front design, and percent slower ramp-up of skills resulting in less productivity for longer duration.

I documented my findings regarding what it would cost our company to set up a reasonable off-shoring arrangement versus hiring locally. Being a start-up with very few people, none of us would have time to travel to India and do the full-time effort required. At our early start-up stage with only Angel Investors we did not have the capital to initially buy a building so I analyzed the “Lease-to-Buy” option with a three-year turn-over. Besides the actual developer hourly rates, costs include:

  • A new local manager position (part-time)
  • Significant travel budget
  • Service company overhead and fees
  • Local manager
  • Average turn-over rates for India resulting in additional new hire travel, training and resulting loss of productivity during ramp-up
  • Yearly increases
  • Loss of productivity of the local team’s time that would need to be spent with remote conferencing, training, and travel
  • Average productivity and quality figures

Needless to say, the yearly costs were nearly equivalent to hiring less developers locally and didn’t improve significantly after the group became employees, although at that time the potential to lower turn-over rates due to stock options and other benefits increased.


My CEO agreed. It was an invalid business proposition. We hired locally.

New Company – New Strategy

When our start-up was acquired, the acquiring company had an outsourcing strategy in-place for its existing product line. Their offshore team performed testing only. Because of the size of that product’s software platform, each remote tester required local hardware and software requiring extensive Build & Release personnel and policies and high-speed dedicated networking from Corporate to India. The company had decided that the city they’d chosen was not a good choice, suffering from high turnover but lack of local talent pool. Plus the infrastructure there was not sufficient.

They chose a new partner in Hyderabad for a Lease-to-Buy plan. Their goal was to move all development and maintenance to India with the exception of new technology development. I was given directions to develop an offshore team for our product line as well.

Prep Work

I hired our company’s prior VP Engineering as a consultant to help me with the initial 3 months effort. Together we put together the hiring plan. She coordinated updating and enhancing the Developer’s Handbook and other on-line documentation and development guidelines. She updated our software process to incorporate the offshore efforts and put together the training program and travel requirements. Fortunately we had a very good process (many of the tenants of “Agile” but not Scrum). We had good tools to aid with the process: Our proprietary tracking software (SD Tracker), PerForce for code check-in, and Telelogic’s DOORs Requirements Management system (since purchased by IBM). All three had web-based interfaces which was key for remote development. SD Tracker had ongoing comments section which greatly aided on-line “discussions”, capturing what was discussed and decisions made.


We would start with only two developers, one tester and one manager who would also need to do hands-on development part-time. The other product line was much larger and had a significant hiring plan. The two product line teams, though, would remain independent since the code was very different. The hardest position to fill was the overseas manager. He/she would be key to the success of the project since he/she needed to be technically skilled to lead and train the new hires plus a good manager. I quickly learned that in India, the engineers do hands-on development work for only a few years then have the goal of becoming a manager. Managers there do not do hands-on development work. Finding someone willing to do both took a lot of convincing, but we were finally successful. The developers and tester were also hired and all four came to California for two months training. The manager had family in India and ended up having to return after six weeks. We were fortunate that he was extremely bright, picked up the basics and the deeper requirements, and although he still was a bit reluctant to go back to development, agreed to try for a year at least.

After the team returned to India, there was a focus on continued communication. One of the lead developers was given responsibility for managing the Indian team half-time (coding the other half). She traveled there and spent a month on-site. Upon her return she regularly scheduled nightly conference calls weekly or more as needed.

End-of-year Statistics

Regardless, ramp-up was slow for the developers. After one year I found the developers were only 20% to 30% up-to-speed whereas in one year local new hires would have been at least 50%. (The software was complex). I also tracked the time I was spending providing additional design documentation versus what would be required locally but also many questions that seemed to require a simple written answer ended up looping several days before it became clear or a conference call was needed.

After a year, one of the developers was deemed unable to perform and was moved to our services team to work on implementation code and a new developer hired and both developers were brought to Corporate for training/re-training. The manager was unable to travel due to personal reasons but had proven himself to have been a valuable hire. A few months earlier, at the end of our release cycle, his team was not able to complete some of their assignments and he jumped in and completed not only his own but any outstanding work. His code was reliable and high quality which is the only reason the release was successful. At that time I discovered that the services company was paying the manager the same low rate as the two developers (since he was also developing) instead of the manager rate I’d agreed to. I was furious and demanded they immediately provide him the raise and feared losing him so also spent time talking to him and making sure he was happy and letting him know how pleased we were with his efforts. Over the next few years the team was expanded slightly (3-4 developers, 2 testers) with the average amount of turn-over and salary increases. The manager remained.

Ongoing Travel, Communications, Travel, Communications

People were continually going to/from India. Any of our Indian engineers who traveled home yearly would take an extra few weeks to go to the site to work/train. All managers (including Directors, VPs) went there at least yearly. The CTO moved to Israel where he was responsible for all Indian operations. Plus yearly we would bring everyone to Corporate to work for a month or so.

The company implemented it’s “Buy” option and all of the offshore team became employees. Plus they have been raming up the size of the offshore team.

Changes Needed with Agile

Then the company introduced Agile. Initially they tried to use the DOORs Requirement System to capture Stories in a separate spec but that was not a good process. First, DOORs doesn’t have an easy way to prioritize and sort requirements so the Product Marketing team (who performed as Agile Product Owners (POs)) exported the Story doc to Excel then went back to update DOORs with the Story Points and other changes agreed to in team meetings. They still needed to update the actual product specs in DOORs and now the tasks in SD Tracker were linked to stories and specs. But the biggest issue was the difficulty in working with the offshore team starting with Stories. They were used to working from detailed specs and the added interaction between them and the POs caused significant time delay. The company smartly decided to hire POs in India to work locally with those teams. For the next release, the company moved to Rally for Agile Story Management. This was much better than DOORs and Spreadsheets since Rally had a prioritization tool and the features one would want to manage Agile Stories. But, unlike real product documents, the Agile Stories, though grouped in Epics, don’t maintain a specific logical readable order – they remain distinct stories. In order to still communicate the business basis, the POs first wrote extensive PRDs using Microsoft Word. Those would be attached to the Epic. The features within the PRDs became Stories in Agile. In order to provide better clarity, extensive Conditions of Satisfaction (COS) were added as validations. To accommodate this, a design sprint was added as Sprint 0. Of course, quickly after the project started, those stagnant Word documents became out-of-date and useless.

Both product line’s Product Management and Engineering Management and the VPs of both organizations spent several weeks in India to kick-off both new releases Sprint 0’s and to train/re-train. Having a local PO improved (but did not eliminate) communication issues since the Indian PO while very intelligent and eager, had a significant amount of information to learn before he could be effective. Local Product Marketing managers typically took 1-2 years to become effective and still didn’t know the breadth of the product after that time but had local product experts to interface with which the offshore PO did not. While I believe a local team could produce deliverable code in a sprint, the use of locally disperse teams requires the addiction of 3+ “Test Sprints” after code complete. This then is more of a hybrid model than strict Agile but seems to be working fairly well. The Product Line has two separate Agile teams including PO(s) and Scrum Master – one at Corporate; one in India.

Same Conclusion

Bottom line – I think this offshore team is as effective as anyone could hope an offshore team to be. A form of “Agile” is being performed, although it is currently not as effective as our prior Practical Software Methodology (an Agile-like process) with a single local team.

There is substantially no cost savings overall.

There is more work for the POs and development manager than interfacing daily with a local team plus ongoing travel costs and interruptions. Particularly when “Offshore” is half-way around the world and trips there require weeks due to travel time.

More effort to complete, more miscommunications, less product delivered.

13 Tips for a New Software Start-Up

I was lucky enough to be the Co-Founder/VP Engineering, then CTO of a great start-up. Great in so many aspects:

  • Great partners
  • Fun, intelligent, hard-working team
  • Customer-driven product vision
  • Successful product deliveries
  • Supportive Board
  • Happy, loyal customers
The best job I ever had!   Intelic

What tips would I give to new software start-up entrepreneurs about Do’s and Don’ts for software start-ups?

Jan’s 13 Tips:

  1. Pick your partners/executives well. Co-founders and/or executive team needs the same vision and priorities and ideals. The team needs to trust the leaders and the leaders need to trust the team. Management needs to talk the talk AND walk the walk.
    Management Team

  2. People, people, people. Hire smart, hard-working engineers. I quickly recruited key engineers plus found a local company to provide consultants for a quicker ramp-up. If someone isn’t working out, do the hard thing that’s right for the rest of the team. Make the cut. This can be really, really tough and we all want to make it work out, particularly for nice, eager folks. But in a really small team, everyone needs to ramp up quickly and contribute.

  3. Don’t Over-hire. This one didn’t seem intuitive to me at first but worked extremely well for us. Our CEO had the belief that it’s human nature for people to always find work to fill their day. No one in a start-up is ever “not busy” – but are they busy on the right tasks? Another way to look at it is “focus”. If there are “just enough” people, then only the important tasks are done, instead of a lot of non-essential activity. In a start-up, non-essential personnel could include managers who aren’t hands-on part of the time, project managers there just to track status, IT resources, etc. Instead, initially hire for the key spots: Sales/Marketing, hands-on Engineers (including somebody that will also manage), one Finance guy (unless the CEO is also an MBA then they cover it). When the product is ready to be released, add services people, IT, Finance, and someone at the front desk.

  4. Keep the software team co-located. Nothing is as distracting to a small software team as trying to establish a remote, off-shoring facility. Team focus is extremely important.

  5. Focus on delivering what the customer wants. If you’re lucky, you’ll have what we had – early employees who had worked in our target business area that were smart and knew exactly what the customers wanted. If not, find those people – they are key to your team. We built a prototype. Showed it to perpective clients. Got feedback. Updated the prototype. On the day we officially formed the company, we had a robust prototype (HTML screens and flow) plus our first customer and $1 million from Angel investors (most of whom were also from our target business area).

  6. Focus on delivering what the customer needs. If you’re building the software, also think about all of the aspects of the product including how the IT managers will want to customize it, install it, take releases. Plan for that up-front in the way the software is architected and built. We did this in the first release through business properties so the clients could change business policies to match their needs. Also the code read from resource files that contained every word displayed on the screen, including error messages (I highly recommend all software be designed this way) so the clients can use their own terminology easily or even localize to different languages. Later we added a GUI configurator. The easy installer was built in an early release. The upgradability was part of the development thought-process. If you’re building software that needs to be installed and upgraded, this is key. If you’re building cloud software then you’ll obviously need to have easy configuration, install and upgrade tools. And plan for global users – review how “time” affects your application and if important (e.g., contract start/expire timestamps) convert to UTC/GMT global time and build functions to handle time appropriately/consistently.

  7. Pick the right architect. Monitor initial concepts and progress and pick as the key architect the engineer with the best sense of a clean and simple design, regardless of whether he had the most experience or was your initial architect candidate. The right architect is key to product success!
    Keep it simple

  8. Keep it simple. Don’t try to build an architecture that will be everything to everyone – build what you need. Refactor as you go along if necessary to keep the code clean and efficient. A simple framework will be quicker to develop new features on, more reliable, and more maintainable.

  9. Don’t be afraid to build it. Your CEO may say to buy, lease, integrate but for a small company if it keeps things simple to build, keep it simple. Originally we used a 3rd party object-to-relational layer. The night before a major demo it failed. If two people clicked the same button at the same time on their separate browsers, kaboom! We limped through the demo by having copies of the app running on each training system instead of the normal browser configuration. Our architect had, for fun, built a layer for his own use and we quickly migrated to that. It was exactly right for our needs. Simple, clean, just enough. Someone years later asked me if I were to do it again if I wouldn’t use Hyperion, said he would. “Better to buy than build. Better for the engineers resumes,” he said. No, I’d do it exactly the same way but start with the build, not buy version. There are exceptions – I wouldn’t build my own relational database, Java compiler, charting package, etc. But I’m not one for adding tens of thousands of external library files to my release “just in case” one of the handy, dandy tools comes in useful. Keep it simple.

  10. Implement a Practical Software Process and Tools. Choose a software process and tools that are simple and streamlined while you’re small but that can grow and support a scaling business model. Our recommendation is one tool that handles your key process (e.g., Agile story management, task tracking) and provides on-line automated spec viewing.
    Software 2020

  11. Focus on quality. Fix the bugs as they are found. Use a quick, iterative method for ongoing maintenance releases. The only bugs that should not be fixed ASAP are ones that are found internally due to some weird, illogical path through the software or that are so small and cosmetic no one will notice them. DO fix even small bugs that are cosmetic if they are visible on the screen (typos, etc.) as they detract from the professionalism of the software. To streamline the process, use a good bug tracker tool. Have a cross-functional team meet weekly to review new bug reports and keep the funnel flowing. We called it our SDRB (Software Design Review Board). In the early years the head of each cross-functional group would attend, including the CEO (who was also Product Marketing). As we grew the QA Director was the lead but still heads of each org attended: Director of Customer Support, VP Engineering, VP Product Marketing, etc. The top person would attend (if in town), else his/her delegate, so decisions could be made at that meeting and each new bug report allocated to the appropriate release. That way, bug reports and client issues don’t get revisited again and again but are reviewed and assigned to the right delivery timeframe once, promptly.

  12. Focus on application speed, performance. Performance is an extremely important aspect of quality. At Ford Motor, when they built CAD/CAM systems internally for their car designers, they found that more than a second delay in when the designer clicked the light pen to when the screen responded would cause the designer to lose focus and made the tool less effective. Screens must be blazingly fast. Anything taking more than a few seconds needs to give the user the option to “click refresh” or go elsewhere to do work while the screen completes (not hold the user hostage until the processing is done).

  13. Lucky # 13 – Work hard but have fun. We had off-sites. Most importantly, we worked to be sure that everyone, even our Indian consultants would attend them. So the entire team became a close-knit group and everyone was treated with respect. We had yearly “Star Wars”, then “The Matrix” movie outings where our CEO handed out hot dogs and popcorn. Make “fun” part of the culture, part of the daily dynamic. The engineering group had fun with humorous email comments (always respectful but cute). As a manager, play along, encourage it. Don’t be stuffy. We added ‘quotable quotes’ to our bug tracker tool so every time someone submitted a new bug or enhancement request, they saw a random quote. Something someone had said but taken out of context and therefore very hilarious to all of us. At cross-functional meetings when someone says something that can be misconstrued, someone will say “Ahah! Quotable quote.” and it will end up in the system. The more a team is willing to be playful, it shows they trust and respect each other.
    Quotable Quote

    As another example, decorating the cubes when someone goes away on vacation. My favorite: The engineers were going to nail a big piece of plywood over our Dev Manager’s office door when he went on vacation but I said “No nail holes in the building!” (We were leasing after all.) Just then our CEO came up and saw what the engineers were about to do. “Wait a minute.” he said and darted away. He returned with his power drill. “We need this! Nails won’t do,” and proceeded to tightly drill, screw, and seal the plywood over the doorway. Gary sure had trouble getting into his office when he returned 🙂

    Of course, the fun is part two – the tip is “Work Hard” THEN have fun.

What is “Respect”

In a LinkedIn thread, someone asked “what is ‘respect’ in the Agile context?”

What is a sign of respect?

Since Agile is team-based, an obvious trait of any well-functioning team, Agile or otherwise, is showing respect for each other. And, after years as a professional, it seemed kind of intuitive to me what “respect” in business is and the same applies to Agile.

However, is it intuitive when there are cultural differences – either global culture differences or workplace cultural differences?

  1. An American had held several meetings in a remote Japanese village. He was on the train returning to the city but had fallen asleep. When he awoke he was sitting by an elderly Japanese man. He said “Have I missed ‘X’ stop?” The man said “No”. A couple of stops later the elderly man got off the train. At the next stop the few remaining people in the same car left. At the next stop the train stopped. The American found a conductor and asked why the train had stopped. He said “It’s the end of the line.” “What?” said the American. He was furious because he had, it seems, only missed his stop by one and could have easily walked back but now needed to purchase another train ticket or find a taxi. Had he been Respected? Disrespected?

  2. There was a discussion about if it was respectful to shorten or change someone’s name into a nickname they did not use. Or to misspell or mispronounce someone’s name. I was reminded about when I was part of a business meeting with gentleman from Japan. We had been briefed as to the traditional meeting protocol.
    The Tradition of Bowing

    At the beginning of the meeting, the representatives from both companies formed a line and one by one as each Japanese businessman came forward they met each person from our company by exchanging business cards, both bowing, and each reading each other’s name from the card, starting with the host. We had business cards printed with English on one side, Japanese on the other. The first man came forward and presented his card. We bowed. I took his card and read his name. Then I presented my card with the English print facing up and toward him. I was to hold it with both hands by the upper corners. Lean forward slightly to bow while offering the card. He took it, flipped to the Japanese side and said “Jan Makuru-san”. Totally mispronounced my name. Respectful? Disrespectful?

  3. In the afternoon during the same meeting with the Japanese businessmen, I was presenting. The lights were low for the projection, the room warm and hum of the projector in the background. Two of the five businessmen were sleeping. Respectful? Disrespectful? Room too hot? Or was I just boring?

  4. More sleeping-on-the-job: It was a Sales Off-Site for a small U.S. start-up. In the morning, the CEO/VP Marketing was giving the presentation explaining the product direction and overview of the sales strategy. He noticed a newly hired Sales Director was asleep. Respectful? Disrespectful? Or was he just bored?

  5. I was newly hired as Director of IT Technology in a company that had only had a few newhires in the IT organization in many years. Most of the members of the IT organization had been with the company 10 years, 15 years or longer – most in the same job for as many years. Part of my responsibility was SAP Basic and two of my system engineers came to me to say they found that last night’s backup had issues – they feared the backup tape drive was failing. They told me who they used for service and could call and have them come in. I said “Great, have them come in as soon as they can”.

    One of the engineers said “Right now?”

    I said “Yes, if they are available.” I wanted to be sure if there were parts needed or any other issues we had the best chance of getting the tape drive ready for tonight’s overnight backup.

    They said “Will do” and started walking away to make the call. Respectful? Disrespectful?

Back to the first example. Was the elderly Japanese man being disrespectful? The conductor explained to the American – “In our culture, the worst thing you can do, the greatest disrespect, is to cause someone else anguish or grief. He knew you missed your stop but if he told you that would upset you. He would never do anything to upset you.” He was not being disrespectful.

What’s in a name? If someone says “Hi Kev” and his name is “Kevin”, is that disrespectful? It depends. Were they doing it in a “buddy/buddy” way, to show familiarity? To show friendship? If so, it isn’t disrespectful (unless Kevin tells everyone he “hates” to be called “Kev” and they keep on doing it to aggravate him). Are they saying “Hey, Bubba” to annoy you? Then yes, it’s disrespectful. If you mistype someone’s name is that disrespectful? No, it’s a typo. Was the Japanese businessman being disrespectful? Of course not! There are many syllables that do not exist in the Japanese language, particularly difficult is the distinction between our “l” and “r”. Adding “-san” at the end is the formal form of respect. So yes, he was being very respectful.

Sleeping on the job? It depends. I knew the Japanese businessmen would be sleeping in the afternoon – had already been briefed and told not to worry about it. It’s common practice. They do a quick nap after the noon meal and wake up and quietly whisper to get caught up on anything they may have missed so at the end they are all still up-to-speed. Was it disconcerting? Yes because they were either sleeping or whispering. Did I take offense or feel disrespected? No – because I understood the cultural norm.

How about the new Sales Director? He was fired shortly after. Not for the one transgression but it was the last in a series of attitude issues that demonstrated his lack of seriousness in learning the job. The once-a-year Sales Training delivered by the CEO himself is the very best place to gain understanding about the company, product, and sales value. Sleeping through that was unforgivable and the last straw. (And it definitely was NOT a boring presentation!)

That last one was a bit of a trick question until finding out more. I saw a glance between my two system engineers as they left and called them back. I said “Was that not the right choice?”

Their eyes got wide and both were “Huh?”

I said “Is there a reason not to do the servicing now?”

One replied “Well, to service the tape drive we need to shut down the production servers.” I was not familiar with these HP systems but others I’d worked with allowed the tape drive to be taken off-line and reassigned without the system having to be shut down.

“It’s only 2 PM, we can’t bring manufacturing down now. Is there any reason you would not want to do it at 6 PM instead?”

He replied, “6 PM is when we would do it.”

“I have to ask, why were you going to bring them down now then?”

“Because you told us to. Our last boss would have yelled at us if we didn’t do exactly what he said.”

“Even if it was the wrong thing to do?”

“Yes – he never wanted to be wrong. We could get fired!”

These two were definitely showing respect upwards. But their old boss had not shown them respect going the other way.

Is there any difference between respect in an Agile Team and respect in general? Respect in an agile team or any good professional relationship is a two-way street. In a top-down management heavy culture, the employees may show respect to their boss (as in my 5th example above) but if their boss doesn’t show them the same respect (by listening to their inputs, asking for their suggestions, and letting them learn and grow) it isn’t a culture of respect.

So what is respect? The list is longer than this but here’s a start of what I think are the most important aspects.

  • Working to communicate clearly. While the elderly Japanese man’s actions are explainable for his culture, the goal is for the entire team to have a common basis of understanding that it is not “bad” or “disrespectful” to communicate if there are issues in the code or other problems – that that is “good” because it keeps the issues from the customer.
  • Asking for/accepting input. This is the two-way-street of communications.
  • Listening to input without criticism. (Also referred to as ‘Attack the problem, not each other.’)
  • Communicating honestly, but with tact and care for each other’s feelings.
  • Evaluating your own feelings. If you are offended by something someone says (or feel disrespected), first step back to question if it is disrespect or lack of understanding. Lack of understanding can indicate either incorrect/incomplete communications or cultural differences. Go back through the first four bullets above to see if you are communicating and caring for each other’s feelings.
  • Working as hard as you can to do the job you have been assigned.
  • Doing as much as you can to help people you work with.

And after further discussion on LinkedIn, this seems like a good set of principle defining “What Is Respect in Agile?”:

  • Communicating clearly in a way that leaves no possibility for doubt on intent
  • Communicating honestly, but with tact and care for each other’s feelings
  • Working to continually improve the way the team functions and interacts
  • Communicating both ways – asking for and accepting input, listening to input without criticism
  • Being supportive of team mates
  • Being considerate of each other and the customer
  • Trusting each other to do the right thing
  • Working hard towards a common goal – contributing to the fullest extent towards the technical excellence of the product

Any healthy work environment requires respect both ways!

Along comes the Cloud

Or – The Best Thing about the Rise of Cloud Computing (and it’s not what you think)


For years the big software “gorillas” – the big ERP and enterprise application vendors – have owned the software landscape. Software companies that took some of the landscape away were purchased by the gorillas, making them monolithic.     Software Gorillas
Software Gorilla

Buying these big apps costs manufacturers millions of dollars. Implementing them requires hiring a Big5 Consulting firm and the 9-12 month implementations cost more millions. In a year or two when the manufacturer wants to upgrade to the next release of the software, they need to call in the consulting firm and pay millions more.

Most IT organizations accept these costs as the necessary by-product of implementing and using application enterprise software. Agile Monkey
The Agile Monkey – Azerity

At Azerity we proved that software can easily be built that is easy and quick to install, manages the configuration upgrades and data migration even for major releases. We did that by building our software with the entire life cycle in mind including installation and upgrades.

Why don’t other companies jump on the bandwagon? IT organizations haven’t demanded it and the software industry has, until now, no motivation to give up the millions charged for implementations and upgrades. This is wasted IT dollars that could be spent on real value items – research, manufacturing improvements, etc.

Enter the cloud. The cloud changes the paradigm. Releases must be quick and seamless. Customer configurations and data must migrate seamlessly. Can the gorillas adapt? Will the IT organizations begin demanding the same level of service regardless of cloud-based or on-premis?


The big software “gorillas” have owned the software landscape for a decade.
Software Gorillas

The “gorillas” are the big enterprise application companies that have been buying all the littler companies to become big monolithic companies. To buy their products costs millions initially, the big consultants charged millions more for implementation and each upgrade is millions more or each release.

When a manufacturer buys one of these enterprise applications, typically they also hire a consulting firm – like Accenture, Deloitte, KPMG, etc. – to work with them during the implementation. They define their current business processes, their “to-be” business process with the new automation. They identify the “gaps” in the enterprise application that the consulting firm will need to fill with custom code. They design the way their screens should look, the user permissions on fields which are then coded in Java or XML to convert the bare out-of-the-box application to a usable system. This can take 9 months or more of a dedicated team from the manufacturer’s organizations, people who should be doing other jobs but now are on a “special projects team” to get the enterprise software installed. This implementation typically costs millions of dollars paid to the Services organization and more lost in the business worker’s time.

Now 2 years later the gorilla releases it’s next major release. The release includes database changes, screen and navigation changes, new features and functions. The manufacturer wants to take advantage of these new features. But they find out that to upgrade, their millions of dollars of custom code will need to be converted and upgraded. All of their database tables will need to be migrated to incorporate the new data fields and perhaps completely revised. Their XML screen changes will need to be touched, at a minimum, or re-done. The consultants must be called back in to design the changes. If new features are to be leveraged then new screens need to be designed. The cost of the upgrade is, again, many millions of dollars.

For years I’ve asked “Why?”

True Story of an ERP Software Upgrade

I worked for a few years as IT Technology Manager at Varian where we used one of the gorilla software vendor’s ERP software. We were preparing for an upgrade. The business side had done their months of review and code changes (and Varian installed a fairly “vanilla” version of the ERP software – as vanilla as possible). So we were ready for the production upgrade.

Rolling out the upgrade first meant upgrading every PC in the company to a newer operating system. That alone was a significant effort and in many cases involved hardware upgrades or new hardware altogether.

Then came the production software and database migration. My team ran the migration scripts over and over on the test systems, timing each step. Then converted the step times to what they could expect on the larger, more powerful (hence quicker) production system. They laid out the plan and rented a room in a hotel within a block of the facility. The notices went up on the screen that the system would be down over the weekend and at 6 PM Friday evening down they came. In a manufacturing company, taking MRP down over the weekend is a big deal. And it can’t go longer than the weekend without real dollar impacts to the manufacturing floor.

The hotel room was so that the system admin and DBA could take turns who would perform the next step. The alarm would go off at 1 AM and Michael jumped up, ran over to the computer center and pushed the button or performed the series of inputs needed to continue the migration process. He returned and at 3:15 AM the alarm woke Ken to do the next step. So on through Friday night, Saturday, Saturday night, Sunday and Sunday night. At 6:30 AM Monday morning both came in for the final production restore but to their dismay they saw a new error message – in German. Fortunately the International Manager was an early riser and showed up at 7 AM. German was his first language and he was able to translate. The system was up a 9 AM – 2 hours late but early enough to not severely impact manufacturing.

I thought “This is crazy! There has to be a better way.”

Azerity – A Different Kind of Enterprise App

A few years later I was responsible for the product design for an enterprise application system. We had some “rules” for our product:

  1. Installation had to be quick and easy. Upgrades had to occur in less than 12 hours. That meant data scripts would be optimized, anything that could be done ahead-of-time would be carved out, etc.
  2. Install size had to be minimized. This means if the developers us a library, only used components from that library would be shipped. (I’ve seen where this can make a difference between installing 1,000 files versus 24,000 files for the same production codeline which translates to software restarts taking a minute or 30 minutes. If each re-start takes 30 minutes, any issue takes users off-line for that amount of time).
  3. New enhancements had to avoid (if humanly possible) making the customer change any of their interfaces or their business processes.
  4. Data migration had to be part of the install for new releases. Not a separate step someone had to come in and do at midnight. As part of developing a new feature or function, developers would check in their migration scripts. Then when each developer checked out the software daily the scripts would run on their local systems; thus testing the migration script. Data migration then was seamless.
  5. A GUI configurator was needed that would manage the XML screens and manage upgrades so changes needed by the manufacturer would be minimal.

The result was that although our product was as robust, large, mission critical as the gorilla software, ours was easy to install and to upgrade.

The downside was that we charged less for our product and our Services revenue was minimal. The big consultants had no interest in teaming with us because installs and upgrades brought them little revenue.

I said “Yea!” It means that our customers only pay for added value. The software gorilla’s customers are paying millions and millions every year for no added value.

It Drives Me Crazy!

It absolutely positively drives me crazy to see the software industry bilking customers millions and millions for unnecessary services. Think of what the US could do if manufacturers weren’t spending these millions fruitlessly. Think of the inventions, additional technical hires and real advancements this money could be used for instead of no added value services. And we wonder why the US is becoming a Sales and Service country and technology is going overseas!

Along comes the Cloud

Computing in the Clouds

Think about cloud computing. When companies offer apps in the cloud, they have thousands of users, each company in it’s own tenant instance with it’s own configurations and customizations modeling the way each does business. When a new release is distributed to the production servers, upgrades must be quick and seamless. They can’t have each company taking 9 months to test and migrate their data and configurations. Companies usually can’t access the database directly nor files on the cloud servers.

  1. Installation has to be quick and easy.
  2. Install size has to be minimized. (You don’t want hundreds of copies of 24,000 unused files)
  3. New enhancements have to avoid making the customer change any of their interfaces or their business processes else when the software releases to production, issues will ensue.
  4. Data migration had to be part of the install for new releases. The companies using the cloud software don’t have access or control of the database.
  5. A GUI configurator is needed that would manage the XML screens and upgrades because the customers don’t have access to the files.

In other words, if a company wants to compete in the cloud, they need to learn how to build enterprise software without the unnecessary services component.

To me, the cloud will “elevate” the software industry and make it more customer and IT friendly. Enterprise App Vendors who are forced by their customers to move to the Cloud will now “have to” do the right thing. I think it’s great!

Confessions of an Agile Blogger

I’m back to blogging now having returned from our great 6-week trip on our new boat in Canada.
Pender Harbour, BC, Canada

I have been contributing to various Agile LinkedIn and other forums – about what works in Agile, what doesn’t. Whether or not Scrum = Agile, if you can offshore and be Agile, how to develop with agility, etc., etc.

The funny thing is that what I blog about is more often my experiences with our “Practical Software Methodology”, not “Agile”. From what I see in blogs and discussion groups, “Agile” (with a capital “A”) means Agile/Scrum or Agile/Kanban – strict adherence to every step and recommendation like a religion. Whereas there are a lot of processes that can follow the Agile Manifesto’s tenants and principles and not be Scrum or Kanban. I call those “agile” (little “a”) or Agile (without the quotes). I think they are realistic for the majority of today’s software projects.

“Practical Software” was the process implemented at Azerity, my start-up. For years prior to starting Azerity, my goal was to take the best practices learned at Ford Aerospace on Government projects plus leverage the work we did with Carnegie Mellon on SEI Assessments (now referred to as CMMI) but throw out the bulk resulting in a lean and clean process for start-ups. As my start-up company grew I was able to hire a top manager from Ford Aerospace and together we implemented the tools and processes we later coined “Practical Software”.

With our Practical Software Methodology we were iterative, produced code quickly, short release cycles, high quality and high customer acceptance. In parallel, we maintained our on-line DOORs requirements specs, our “bible”, which were part of our process and which were accurate, tested, used by developers, QA, the Call Center, and Consulting. When we sold the company, the on-line DOORs specs were key to the value of the IP. Other developers could be hired, people come and go and even I could quit and the DOORs specs lived on. We were able to maintain those accurate documents with minimal cost because they were part of our development cycle and were iterative. They were not big waterfall Word docs but living breathing statements which matched the tasks assigned to developers to implement/update.

  • We were small and we honored individuals, required feedback and interaction. Our process and tools supported and enhanced the interaction, didn’t detract. We had no organizational silos. There was no throwing of documentation over the wall to the development team. We were a cohesive, single entity building an exemplary product. Quickly. With very few engineers.
  • Our goal was working software since that’s what the customers wanted and what we were paid for. Our process required us (me primarily) to have the documentation/specs to be in place in time for testing but the docs were a reflection of the code, not the up-front mandates from the waterfall era.
  • Because two of the three co-founders plus other key members of the company came from the customer’s industry, we had the unique advantage of knowing what the customers in our space wanted so the software was accepted and loved by our customer base.
  • Because I was one of the co-founders, I had the “red pen” and could slash out features if we needed to make a hard release date or visa versa, move the date if needed; thus able to respond to changes, not follow a fixed plan.

We followed the Agile Manifesto tenants:

  • Individuals and interactions over processes and tools
  • Working software over comprehensive documentation
  • Customer collaboration over contract negotiation
  • Responding to change over following a plan

Agile and it’s related methodologies (XP, Scrum) were born in parallel to Practical Software. I was previously a skeptic about Agile because whenever I heard someone talk about implementing “Agile”, they also added “throw out documentation”. Just talk. Sticky notes on a white board. Since my background is building large-scale mission critical software applications with extensive business practices and policies incorporated in the code, where the product was already so large even I was having trouble remembering every business requirement, I couldn’t envision how our product would/could ever be managed, evolved, and maintained. Plus our process which included on-line documentation was so clean and efficient it was hard to understand why other companies were struggling. (I’ve since come to realize that others haven’t found the secret sauce – how to maintain documentation in parallel without impacting development timelines).

A few years ago I was converted from an Agile skeptic to a proponent. The company that bought Azerity was implementing Agile or a hybrid thereof. I became a certified Product Owner. The interesting thing about my Agile training was that my objections to Agile ended up being objections to some form of Scrum or to a misunderstanding others had of the Agile principles or to some other misuse of Agile tenants. In reality, what I learned was that at the core of Agile (the Manifesto) were the very concepts that were at the core of Practical Software. Which makes sense. The initial proponents of Agile were seasoned software professionals who looked at how waterfall/phase-gate projects were being done, saw the issues, and proposed a better way. We at Azerity looked at how the big government waterfall projects were done, saw the issues, and proposed a better way. Many if not most of our findings were consistent.

I now believe the industry is being improved overall by the consistent message and training coming out because of Agile. I still see issues in the Agile communities:

  • There is still a tendency for some to convert the statement of “Working software over comprehensive documentation” into “No documentation”.
  • Scrum to me seems too rigorous to have innovative iterations on a less structured schedule.
  • Agile seems development-focused and thus loses some of the bigger-picture concerns such as delivery, customer upgrades, other organization’s needs.

Both Agile and Practical Software solved what I saw in government and commercial software companies as the main issue – the issue of organizational silos and phase-gate workflow. “Business people and developers must work together daily throughout the project.”

I am now an Agile proponent (or should I say “agile” proponent). Please excuse me if I’m sometimes blogging about my “Practical Software” experiences ☺

See how we automate documentation with 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:

    “On all screens, in the white top banner, there shouldn’t be a title/words between the logo and tabs (now shows dash + Page Title + User’s Name). Instead the Title should be white and centered…”

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.

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.