No one reads the documentation – and that shouldn’t stop you

library-488678_640I could make a post with the perfect tone mix of “amusingly angry” and “cynical tech guy” on how no one ever reads the manual, but this is not about making a point on how clever “we” are versus how dumb are “they”. I can recognize that once or twice I’ve been tempted to answer a basic query on software with a RTFM or JFGI (which, if you don’t know the acronyms, are not in the slightest the polite and correct way to address a question), but falling for raging retorts is what slowly turns any workplace into a toxic one. Instead, I’m going to be constructive, and point out how to avoid a critical pitfall for software development.

People that have worked with me know how much of a dedicated documentation writer I am. Well, I actually enjoy writing as an activity (this blog bears witness to that fact), but reference creation is not the most enjoyable activity. So no, I don’t write technical papers as a hobby; I do it because it is a necessity.

Time and time again, you’ll find yourself going back to old projects. Maybe to add a new feature, or perhaps to reuse a library that can be helpful on new designs. Or perhaps it’s a legacy component that requires an upgrade, that you have inherited from an employee that no longer works in this company. I guess I don’t need to tell you how fast paradigms and frameworks evolve, change and are discarded. So chances are high that the old project is outdated. That means that any kind of modification, unless correctly explained, will be a painful experience.

Let’s take a minute to consider this: What do I mean with documentation? Well… More than on the functional level, I am referring to the technical records that explain design decisions, inner workings and intricacies of the code. When you are developing a specific feature, the reasons behind the implementation you adopt can be obvious – and notice the italics there. Your train of thought is fresh, and the many deductions extracted from the requirements analysis brought you towards specific decisions. But as time passes, the basic reasoning behind those choices will fall, and you will stare puzzled at that fragment of code.

Now, imagine the scenario where that code isn’t even yours. You better enjoy solving riddles, because you just got yourself one.

Sometimes, you don’t really need to invest long hours into drafting, polishing and editing your writing. A few lines can do, and diagrams or graphics are sometimes even more helpful, as the proverb goes.

As a final footnote, make sure that your record gets proofread by a peer. Otherwise, you might fall into the trap of allowing a concept that you believe obvious to fall into oblivion.

Answering the underlying question: why should you write documentation? Because memory fades, and you need some sort of insurance protection against future extensions.

What is it that makes a good developer?


I’ve always found that, when interviewing someone for a technical position, the round of time talking about actual technical knowledge is the one taking the smallest fragment of the conversation. And this is because all technology can be learnt with proper attitude and effort, but you don’t exercise and study to get the proper behavior.

This does not mean that the skill screening is not necessary. If the position requires a degree of expertise with a very specific tool, chances are that you do not want to invest a long learning curve for your new recruit. If the project is already underway, or on maintenance life cycle, perhaps a candidate with profound knowledge of the core framework is a better pick than a junior with rudimentary experience with the programming language.

That said, a thief knows a thief: you need a developer to recruit a developer. Or at least someone who had the experience in the past. Because that’s how you will quickly distinguish the candidate from the expert, and you can jump towards more interesting topics.

So, back to the original question. What does make a certain developer a good one? I’m going to present a few ideas that I believe are the backbone of an efficient programmer and an outstanding worker. They are all important, and perhaps not all of them are present in a certain applicant, but find some of these, and you’ll have good markers for appropriate business fit.

Foremost, the ingenuity. Not knowing how to do something is not the same than not being able to do it. It may look conflicting on a first glance, but that it’s just because what we are looking for: a developer’s job is to create software that performs specific needs, and this means that there are endless ways to do those actions . Do not ask on an interview for boring solutions to textbook questions, but present a real problem instead. Give all the information you can on the problem, and listen to the questions that the interviewed formulates. Encourage him/her to talk aloud, to explain their train of thought: being able to follow a pattern of deductions and present a solution shows creativity. This resolution might not be robust, or the best approach, but what you are putting their lateral thinking skills to the test, not their ability to present a solution under the effects of pressure and stress.

With the previous inquire you also probe another critical attribute: the “need to solve”. I’ve noticed that a good developer is somewhat of a tinkerer: they are driven to pull things apart, and then putting them together again. They thrive with the need to know. You can notice if the candidate holds this mindset just by answering their questions. Make sure to withdraw information from them in the problem previously presented, and see if their curiosity appears. Keep in mind that looking for specific questions is not the objective of this exercise. Do not expect a certain number of queries, nor “quality questions” to accept or reject a candidate. This is not a binary problem, and you shouldn’t address it as such.

Next, look for passion. This can manifest in the form of a technology-related hobby, or perhaps they have a blog related to their trade. Try to get a hold for their motivation. The best developers are challenge-driven, willing to learn, and willing to offer advice.

Ingenuity, urge to solve, and passion. These three attributes make any aspirant into a workforce by itself. Technologies, languages and tools come second, because they can be taught. Attitude is what you should be looking for.

How to introduce technical concepts to management


I’ve heard many times the statement “technical guys talk another completely different language” after a demo meeting. And although it’s usually passed on as a joke between folks outside the development chain, it reflects the lack of connection to those ideas presented. For us “techie folks” a console screen with may log lines defining what is happening along with a very very long sentence including those kind of verbs that you won’t use in a regular conversation is the very embodiment of excitement (or it is for me!). However, that tells nothing to somebody that is not used to work with computers on a profound level.

Teams working under scrum methodologies put effort on setting up a demo showing new features after each sprint. They are engaged and excited after performing complex jobs, and proudly want to shout “hey, take a look at what we did!”. And for the duration of the meeting, they are met with stares of boredom, or even complete disregard. After the slides, when the feature is demonstrated, the attendees might give a glance or two at the screen, perhaps. And then, they will quickly return their attention to their mobiles, the ceiling, or their nails. And this leads the team to resentment that will turn eventually into feeling neglected from their managers.

Not the most exciting presentation...
Doesn’t make for the most exciting presentation…

This is the perfect opportunity for scrum masters to involve themselves on the team retrospectives. If your team didn’t adopt scrum, a similar role can perform this job: product owners, technical leads, middle managers… The team needs someone able to translate “technical” to “business”. That is because they speak of very different things.

Teams want to talk about technology, features, processes… They desire to spread word of their preferred library, of a new component, of architecture and microservices. But what the leading people want to hear is about customer impact, time to market and benefits. They specially want to hear about how the investment is going to turn into profit. Balancing loaders? Forget about that, talk about doubling userbase capacity. Automated testing on each Release Candidate? That is an impressive achievement, but what will move the bosses is making them understand that the QA phase will be shortened.

You have to employ simple terms. There is no need to explain in detail your architecture, because -and this is a fact- they will not understand what is going on. Stress that, and then read it again. Then tattoo it on your arm. Accept to live with that fact, because that is exactly why you are hired: you understand technical concepts way better, you apply the required best practices for software, and you are the one making it happen. It is not about the how, but the why. If you really must talk about technical stuff, use metaphors. Balance load and data consumption easily transform into a highway with vehicles. Memory usage can be explained with cookies (or any other food will do, actually). Data architecture nodes can be warehouses and stores, being provided data by vehicles… See what I mean? Use the very raw concept behind the technology, but avoid it altogether if you can.

Color-coding is also a great strategy. Use comparisons before and after the changes. Use graphics, arrows pointing up and down. You do not need to make use of real data, although some numbers will have to be provided to back up your claims. Use icons, screenshots… Why explain how to arrive to a specific form on a website, when you can show it?

As well, record your presentation in video form. Play this video in the background, on your explanation, while you perform the exposition. This will give your speech cohesion, will allow you to focus on your audience. Your body language says a lot to those in the room, and being vaguely aware of what is happening on your screen while you try to recite your script does not back you up.

Finally, it is recommended to include reminders of older presentations. A slide or two to refresh a term in the form of quick recaps will put everyone on common ground – especially if an attendee couldn’t appear on the latest performance.

Try applying these ideas on your retrospectives, and let me know if you notice a change of attitude on the observers.

Be clever when automating

knob-393044_640Manual processes and authorization bottlenecks tend to become the proverbial nail in the coffin when automatization initiatives are adopted. The refusal to bypass these old-fashioned control gates can doom the project, so let’s review the reasons that can lead this effort to ruin.

The first items to be mechanized in software development tend to be those related to the deployment of the applications (the whole get-latest, compile and install pipeline). It also holds as a proof-of-concept of sorts: the team will rationalize that if they can make a script for this process, they can also program one for any other task. While this is mostly true, they are forgetting the human factor on the equation.

Once the deployment pipeline on the development pipeline is automated, new items will follow: packaging, unit testing, and maybe some end-to-end tests as well, or perhaps infrastructure provisioning. And then, your team will feel confident enough to tackle release management.

This is the moment where you, as a director, must involve yourself into adopting the new automation strategy. Your help is not only necessary to find the steps to be turned into code, but to convert those managers that hold tight to their reins into the new way of doing. Most people will feel like automating their tasks will reduce their visibility or what they are worth. This statement is especially true for those people whose only job is just giving a “yay” or “nay” for a deployment to sensitive environments like pre-production or production. And, feeling like they can be “let go”, will do their best against the automation of their area. You need to identify these risks, ease their fears and work together towards a common goal. Make these managers feel involved into the adoption process with new tools. A dashboard tool with the state of the package with a resume of the release’s state can become a useful way to monitor a deployment’s process.

TFS/VSO included a Release Management dashboard that displays the current step of a deploy

An important part of any automation process is the re-engineering of processes. The strategy must change – will change – when decisions are made in the design phase of the project, as originally intended. You are not really losing dynamism, as at any given time you can push back the state of a release and go back to the blackboard and change staff. But the important part is that allowing the flow to proceed only in one direction actually makes you go back to the beginning and start anew. No bypasses reduce room for mistakes and forgetting important but tedious steps that the computer will be taking care of.

Technology adoption is more than just changing your tools

sandhill-crane-824650_640Allow me to start this post quoting the first principle of the Agile Manifesto: “[We value more] Individual and interactions over processes and tools“. The aim of this postulate was to benefit human exchange and improve communication between workers rather than adhere to protocol and bureaucracy. However, I’ve found lately a new meaning if we apply this teaching to the process of adopting new technologies.

You may have heard of “innovators” and “early adopters” in the context of embracing change. These terms are applied to the first two groups that accept a new tool on their process and the amount of social media involved makes it look like some type of “techie award”. Adoption is not – and should not – be a race. Some business’ benefit migration more than others and the important message is to embrace this evolution, and make it your own.

Groups of technology adopters

Thus, rushing the change of your tools is something potentially damaging. Adopting software that does not meet your structure is toxic. And changing for the sake of removing the “legacy” tag is doomed to fail. A transition is an organic process, not a magical transmutation. Is more than a management decision, and forcing employees to assume the use of a tool that does not fit their needs will only make things for the worse.

As well, new instruments should be used for what they are, not for what you need them to be. It may be okay to bend the defined limits of a new technology to fully fit in your company culture, but if the software needs heavy customization, or private components to integrate to your existing stack… Well, maybe it’s not the tool for you.

That said, maybe you truly are in the path of a correct technological adoption, and this components or twists are just a necessary evil that will disappear in the long run. That is okay, although it will still be harmful for your department. Make sure that everyone related to this trend movement is up to date, and work towards smoothing out those sticking points in the critical procedures of your mission.

So, if new tools are necessary, just take it easy and don’t perform a half-assed transformation, unless you want to bring the old issues to the new processes.

Dont’ worry about making mistakes – as long as you don’t make them in production

wood-cube-473703_640You know what’s wrong with your development or integration environment? That, most probably, is “broken”. Meaning that a component isn’t working as intended, or a dependency wasn’t upgraded to the required version, or maybe a legacy application still in production is not properly initiating.

And you know what? It is completely fine. Because that’s exactly what development, sandbox, integration and all those non-productive environments are for.

The issue, however, is the time wasted trying to solve those problems. Promoting a release artifact (a candidate of your software) requires a certain level of quality, and a broken environment is hardly a valid context for validation. So, usually, the last days of a sprint are wasted in a timed race to fix all inaccuracies in the application’s ecosystem. Chances are that, in a hurry to make it work, someone broke something else. And there you have your infinite loop.

If your non-productive environment is shared amongst several teams, the concern is magnified tenfold: a configuration or prerequisite changed by the other crew now made this team’s software unusable. Then the finger-pointing and the blaming start, and toxicity levels rise. This calls for additional management and diplomacy skills.

However, there is an approach that can solve this altogether. You could define your artifact’s whole prerequisites as code, and then use that information to create from scratch the necessary hosting machine. Tools such as Ansible, Vagrant and Docker, to name a few, have very straight-forward ways to implement these essential elements to set up a self-provisioned environment. The operative system, third party libraries or even private components developed on your department can be retrieved from an internal repository to speed up this process.

Another advantage to this approach is to have “ephemeral” environments for each step of your artifact’s lifecycle. Why should you keep a machine up and running when you can fire up one anew in a matter of minutes, and then trash it when you’re done? Make the math: you’ll be saving money in costs using machines on demand.

As a final thought, consider for a minute how this approach makes the most out of Continuous Integration / Continuous Deployment tactics: with each code commit a container could be created, the artifact deployed, automatically tested, and packaged as release candidate if all quality gates are approved. Cutting out times to market release makes everyone happy: from developers to your market user base.

This strategy is called “Configuration as Code”, or “Infrastructure as Code”. And this will make sure you never worry about having errors on development, ever.

Stop using Excel as a collaborative tool

anvil-416186_640Thinking outside the box, as a skill, can help solving issues in a non-conventional way… Unless the basis for your lateral thought process involves a spreadsheet.

So far in my career, I’ve witnessed this application being used as an ALM, as a calendar, as Key-Value translator, and even as a string localization tool. And in all of those cases there was better software available to do that very same job.

It’s understandable in some cases: the technical gap makes us look for refuge in what tools we already know and master. But the fear of the unknown is no valid reason to design clumsy processes and protocols. Let’s point out why.

Foremost, Excel is not a collaborative tool. There are no good mechanisms in place for several people to edit a file at the same time. Finding a slot to enter your records might as well turn into the plot of some epic movie with its own faux latin soundtrack. And then, failing to refresh the cached data when the file is available again can turn into the loss of the information entered by the previous user. Having no centralized control makes it arduous to keep a “hard master” of the records, and that, in turn, forces the users to redundant controls or empowering a single user to perform all edits.

Which brings us to the next point: entering data is cumbersome. Something as simple as formatting a date with hour on am/pm might depend on the localization of your machine. On multinational companies this regional values can be forced to a standard in the company, changing annoyingly the values you just entered. So you have to delete, and start again. And of course, if you made a mistake with formatting on the first row, the whole column will now be preset to the data values you entered incorrectly. Then there’s the fact that every department uses their own customized templates, and all of them are different, use different formula to extract information, or either their final results are in a configuration unusable for you. Whoops! Time to write yet another excel parser, then!

Finally, let me emphasize an issue of importance: data cannot be connected. There is no built-in gimmick to generate master records and relationships, because Excel is no database software. Something as innocent as inserting a single row, or dragging a data range, can break your carefully executed plan. Tracking any misalignment will be a waste of valuable hours of work, and nothing guarantees that this slip won’t be happening again sometime.

Since I don’t want to keep dragging the point, let me do a quick recap on a few more issues out of the top of my head:

  • Does not include real-time information update.
  • There is no user traceability on who performed changes on data or formula, nor verifies if the values are correct and valid.
  • Spreadsheets are not secure: information within cannot be verified, and it’s easy to insert malicious macros.
  • Files cannot be attached.
  • The software was not designed to be used this way.

I think it’s pretty obvious. Can you risk keep using this tool and slowing down your success?

“Trolling” as strategy for security

plumbing-840835_640One of the most difficult security business rules to enforce in companies is the “mandatory lock account” when you are not in front of your computer. Entering your credentials over and over again is seen as a waste of time. Why should I lock my session it if I’m going away for just a few minutes? What could go wrong during a tiny coffee break?

Let’s not delve into the huge list of things that could go downstairs from that specific security risk. After all, if you are trying to encourage safety, it means that your assessment is done and your conclusions drawn. Since you are building up approaches to safeguard your information, let me tell you about a simple tactic that will persuade all staff to hit Windows + L mechanically before standing from their desks.

What do I mean with “trolling”? I bet you heard the Internet slang term to define those individuals that aim to start arguments or provoke emotional responses, taking advantage of their anonymity. The idea behind the approach I’m proposing is that your coworkers are the ones that enforce your security rules upon each other, fearing what retaliation might bring if they fail to do so.

A widely accepted way to play this game is to invite all coworkers to beers after work via email to the whole team’s distribution list – and of course, pay for it! Another valid strategy is to “do the hoff”: installing a chrome extension that replaces all images in the user’s browser with pictures of David Hasselhoff, along with changing the corporate desktop background.

It’s important to define clear boundaries. After all, if it exceeds the red line of what is playful teasing and goes beyond that into real personal damage, it will damage your employees’ comfort and performance. Don’t let it go too far. Taking this to life outside of the office, or damaging the work they are doing is completely out of the picture. Everyone should aim for simple pranks and practical jokes.

So go ahead: send an email reminding the whole company that they should not leave computers unattended without locking their account. State clearly the rules of what damage does it bring _to their own persona_. Encourage email writing impersonating someone (without writing to any external address. Keep this “inside home”) to treat companions. And close up the announcement with a prompt towards fair play. And notch it up a gear: make yourself an available target! Leading by example is the best course to direct changes.

After that, you will be double-checking your computer before leaving the office… But it sure is worth it.

How the workshop mindset is hurting software development

germany-1367255_640Software factory defines a paradigm of development that mimics a production line factory. Each component is processed as a physical product, adapted, assembled and configured to make a whole item with a specific purpose. However, I am going to refer in this post to the “software factory” as the mindset of the early 1900s that led into movements such as worker’s day and other laborers revolutions.

The software engineer is somewhat seen as a cog in the structure of the company, just another asset that it’s exploited. It can be replaced. It can be abused, forced to work overtime. And you might probably think from this preface that I am going provocative with this post, that I am attacking business’ management. Just wait, and read with an open mind. I’m not going to write this post from the point of view of a revolutionary, nor do I aim to debate social and legal issues. No: I am going to talk about money, profit, and talent.

Let’s start with an obvious remark: software developers are people. This means that they are subject to changes in their performance. Some incentives are obvious: an adequate work environment, correct payment, sensible shifts… But have you considered the less exposed reasons? There are metrics such as peer recognition, the project’s level of interest, or the degree of implication from a team, to name a few.

And then, there are the negative markers. These are what make a worker “burned out”, which is the level of disengagement that a given employee suffers. The “workshop mindset” or making your business into “software factory” is what emphasizes these drawbacks. Dull working hours and removal of the creative process of a piece of software quickly turns into non-involvement. A software developer needs to have a certain connection to its work, or the value of it, because there is a high level of creativity related to the process.

All of these “measurements”, both positive and negative, fall under management responsibilities. And, unless correctly addressed, will turn a hire into a job vacant.

This brings us back to the previous statement of “any software developer is replaceable”. Any time you lose an engineer, you are losing expertise. Getting to know the commercial culture and the intricacies of any business takes time and effort, and that translates into money. If you pay someone to become a part of your trade, and then allow them to leave because you did not address issues inside your company, you are losing wealth generation.

Take into consideration that it takes four to eight months for a software engineer to start “producing” effectively. There are protocols to teach, people to meet, and details to gather. Even the most thoughtful “welcome pack” will leave information out of the training course. It might even happen that the employee that left the company had valuable knowledge still not transferred to other coworkers, and that will hurt your department.

What can you do? Do more than just hiring talent. Nurture it, make it grow. Allow teams to have a voice in the product they are developing, and make sure to let them understand what they are committing to. If overtime happens (and I stress the “if”), a software engineer will invest their own time if they feel like being part of the outcome. An engaged worker is more productive than a cog, so reject that century-old mindset and make the most out of the skill of your employees.

Improving your deployments with Blue/Green strategies

soap-bubbles-817098_640The most common scenario is that you spent weeks tuning your deployment to production. You suffered through testing and, finally, the end of this release is here. The deployment to production starts… And the application isn’t initializing. Something freezes along your spine as the consequences of this downtime slowly dawn on you…

Does this short story sound familiar? I bet that we all technical chaps suffered through this experience at least once in our lifetime. Then we define rollback plans, contingency interventions, prayers and offerings to the tyrannical data gods… And, in the end, we learn about Blue/Green deployments.

So, what is this about? Let’s picture a basic scenario for what our production environment could be:

Simple enough: a server holds an application that attacks to a database, and the users connect to our server. Now, instead of deploying directly, we will publish the new version of our software to a clone of this machine, and redirect part of our user base to this computer. Check the following diagram:

If the “green” environment has any defect that prevents the application to start, or there are any errors that automated testing can detect easily, the promotion can be rejected without any impact on our users: they will still be using the version 1.0. However, if it looks like all is correct, we slowly redirect access to our version 1.1.

Take notice on how both versions of our software are using the same database (now highlighted with a third color to make clear enough that it’s not subjected to a single environment). This means that we have to take into account additional considerations when altering the structure, as the current and previous version of the software will coexist for a certain amount of time.

A best practice approach to solve this obstacle is to detach the column or table from the data model in version n, then executing the script that actually removes the element in version n+1. Since there are no “hard links” to the feature, no errors would be generated in any of the blue or green environments when performing deployments.


The key to successfully adopt Blue/Green tactics is to automate your environment creation. “Infrastructure as code” approaches that generate your servers on demand on a repeatable and steady form eliminate human error from the equation. Either something as simple as a template for your virtual machine or as complex configuration management and prerequisite inventories allows you to roll out new versions of your product with a minimal collision with your user base.

Oh, and let’s not forget about the mental health of your operations employees. They will be grateful to stop deploying with a sense of impending doom.