Software Process

The Why and Why Not Of Documentation

~ Taran ~ Leave a comment

FAIL stampMy core pet peeve of the last 10 years is the lack of documentation I’ve encountered with Software Projects. Sometimes it’s as the consultant that’s called in after someone already charged a lot of money for a substandard job. Sometimes it’s that legacy project that sticks around through generations of developers who leave a company. Sometimes it’s the “we don’t have time” factor.

Documentation is a value-added part of any software project for a variety of reasons:

  • Reference: The ability of software engineers involved with a project to look back and see why things were done the way they were, and to allow for knowing the limitations and potential of a project.
  • On-boarding: Bringing new software engineers up to speed quickly without having to bounce around the company finding answers.
  • New Projects: Proper documentation of old projects, including estimates and other data, is of great use for estimating similar projects. (Project Management and Business Analysis)
  • Complicated code reviews are simplified.
  • If someone gets hit by a bus, someone else can take over. Quickly.
  • Legal: If a project is supposed to meet certain requirements, those requirements should be traced to the actual implementation.
  • Teams: Proper documentation in an Agile or DevOps process allows team members to see what others are doing in similar areas of code, and allows easy identification of problem areas quickly.

These are just some of the reasons documentation is important. More often than not, I’ve ended up writing documentation at different companies because it simply did not exist before.

Why didn’t it exist? Here are the standard excuses:

  • No Time: We didn’t have any time to write the documentation because we’re busy working on the next thing!
  • “Me no write so good”: Fair enough, but there’s only one way to get better at writing.
  • “It’s not my job, man”: Erm – no. Documentation is a part of software engineering. A big part.
  • We don’t know how to organize it: Fair enough. Spend some time and figure it out and implement it.

At the base of all the excuses are 2 things that are really simple:

  1. Software Developers generally don’t like writing documentation.
  2. Management fails to have developers write documentation.

These 2 things are understandable, wrong, and amazingly easy to deal with if a company wants to.

Evolution: Process Trumps All

~ Taran ~ Leave a comment

3D view of Mar03wjc1bOnce upon a time, software was sold on disks that were actually floppy. They were encased in boxes, with user manuals.

Then the disks were no longer floppy, but they were called floppy as a sacrifice to the Gods of Inaccuracy.

Then the Internet came along, and you could buy the boxes over the Internet.

Then you could download the applications over the internet when you purchased them.

And finally, Software as a Service (SaaS) came into being, and all was basically the same only faster (and with significantly worse documentation).
And the people were generally as miserable as they were, and could be disappointed at a faster rate when they found bugs, or when systems went down, or when their internet access was sloppy.

The real difference between competing companies now is how they produce and maintain the software. That’s the process.

Bugs happen. How fast can the bug be fixed, without introducing new ones? That’s the competition. That’s where competing companies actually should be competing, because the faster a company can fix bugs, the faster it can implement things as well.

That boils down to Software Process. And that’s why Agile, Lean, DevOps and so on are so important.

Because nobody is ordering boxes from the back of magazines anymore and getting it in the mail a few weeks later. They want it now.

If you don’t even have a software development plan (SDP) for a project, you’re already behind.

 

 

 

The Confusion On DevOps

~ Taran ~ Leave a comment

devops in a boxI was in an interview with a candidate for a Software Engineer some time ago. We had the usual suspects at the table and me, the unusual one at the interview.

I’d read the guy’s resume. He claimed some game programming, and he also claimed to have experience with the full SDLC with both the Waterfall and DevOps methodologies. One of our people, notorious for academic questions, was pulling some of his punches related to .Net. He trotted out his usual questions on design patterns (he sure did love his MVC – let’s call him Mr. MVC), and he continued with his notorious monopolization of the interview. When it finally got to my turn, I asked a XOR question – the candidate had never used it.

So then I asked him about the strengths and weaknesses of Waterfall – and on DevOps. Mr. MVC quipped that he didn’t think we were hiring for the DevOps department, and I ignored him since I did not want to straighten out his ignorance in front of a candidate (though he had no problem being a jerk when he was wrong). The candidate answered the questions well enough, and I let it be.

But looking back, I couldn’t help but think that Mr. MVC was confused by DevOps because:

(1) We had a department by that name.

(2) He didn’t actually know about what DevOps was,

(3) He hadn’t read the resume and noted ‘using Waterfall and DevOps methodologies’.

It surprised me that Mr. MVC didn’t know about it, and it surprised me more that he’s now basically in charge of the Agile process at that company but wasn’t familiar with DevOps itself – particularly when the end goal is continuous integration. That’s sort of what DevOps is:

…Agile software development paved the way, steering away from the waterfall method of software development toward a continuous development cycle. But it didn’t include the operations side so while development could be continuous, deployment was still waterfall-oriented.

In a DevOps environment, cross functionality, shared responsibilities and trust are promoted. DevOps essentially extends the continuous development goals of the Agile movement to continuous integration and release. In order to accommodate continuous releases, DevOps encourages automation of the change, configuration and release processes…

So, by having DevOps on his resume, the candidate had opened himself up to all manner of questions on Agile, as well as continuous integration – things which, months later, would be brought up by the CTO.

And no one – not one soul – called it DevOps. Why? Likely because they got rid of the department that they used to call DevOps. This was largely because they sabotaged it by not giving it the appropriate tools for continuous integration, and the fact that the lack of documentation made the relatively fresh department more likely to fail with manual deployments.

I write all of this because I encountered it at one of my own interviews with a company. We were talking about continuous integration and the mismatch between Agile and Continuous Integration when it comes to involving Operations – they are typically not involved with Scrums and are therefore less likely to be prepared. That’s where DevOps comes in.

DevOps has been around a while. Waterfall went to V-model that went to Agile – and now DevOps is king. Or should be.

But it’s surprising how many people don’t know about it.

Suggested Reading: