As software developers we care about the quality of our code, about our test coverage, about design and architectural principles. We study algorithms and design patterns, we experiment with the latest programming paradigm, we fall in love with certain IDEs (or lack of), and we practice keyboard shortcuts as diligent Zen disciples.

Then we become technical leaders, and we bring our approach with us: we investigate new processes (Scrum, Kanban, Lean…), we happily obsess about collaboration tools (Jira, Trello, FogBugz…), we fight the right cause for the latest test automation fad (TDD, BDD, ATDD…) and we become enlightened after discovering Continuos Delivery.

But what about the human side of software development? What about commitment, about passion and team morale, about working towards a common goal, about developing trust and communication? How much we invest on those?

I’d like to claim that in our industry we underestimate the impact of the human factor on the success of our projects and on the technical quality of our delivery.

I’m a geek at heart, and I wish I could now cite some researches and rattle off significant numbers to back my ideas. But I can’t, and what a pity it’s the lack of scientific studies in software engineering.^[1]

In the last 10 years, following the shift in perspective brought by Positive Psychology, lots of researches and studies (and Ted Talks) have been made about the impact of happiness, wellbeing and motivation at work. Businesses like Zappos have started a “happiness revolution” focused on culture and positive attitude.

But – even if some technical companies such as Buffer are already part of it – this revolution hasn’t touched yet the core of our industry. The missing piece of the puzzle is, I believe, the awareness of how much the human side of our work affect the success of our technical projects and even the technical quality of our codebase.

Lacking scientific proofs, the best I can give you is a bit of anecdotal evidence from my personal experience. That’s why I’ve been writing this series of articles, a story of a team in a big enterprisey media company and its redemption from dysfunctional to amazingly brilliant.^[2]

I was part of that journey, and along it I’ve learned some valuable lessons. Without further ado, here are the most important ones, in a “bloggy” dotted-list fashion.

Lessons I’ve learned

People and interactions over processes and tools

I’ve witnessed many times teams with collaboration problems being unsuccessfully prescribed a cure based on pre-packaged processes and tools (Scum or Kanban? Jira or FogBugz?). Processes can only lead you so far.^[3] But if you can build trust and honesty, if you can establish open communication patterns and have everyone in the team passionate about a common goal, then you’ll really shine and deliver.^[4]

Hiring and keeping great people is the most important thing

It’s a cliche, but it’s true: there is nothing more important than hiring the right people, and doing everything you can to keep them happy. I’m not talking about the technical skills, but mainly about finding people with the right attitude. Technical skills can be learned, but negative behaviours can be a drag for the whole team.

Culture-fit is not an option

I worked in companies where the main requirements to hire contractors where years of experience in a specific language, and even in a specific framework, following a specific process. That’s all good, but not as important as cultural fit. Hire people that fit within your company and team culture.

One team, one goal

As developers we are often concerned with maintaining technical quality up to standards, while project managers or Scrum Masters are mainly worried about delivery and deadlines. Sometimes testers too perceive their main goal as antagonist to developers.^[5] All of this is really counterproductive, and leads to politics and paralysis. Find a unique goal that is shared by everyone, let developers and testers also care for deadlines and delivering in time, and let product owners understand that technical quality is nothing but speed of delivery in the long term.

Values matters

You don’t need to write them down. The best values are hard coded in our habits and unspoken. But if you can, try to have them clear in you mind. Especially, consider their hierarchy and priority. For instance: do you value customer satisfaction more or less then code craftsmanship? Do you value respecting each other’s idea more or less than code correctness?^[6] Values are the hidden DNA of a team.

Trust is the best productivity booster

Big companies invest a lot of money in safety procedures. I used to work in a company where each deployment required approval from a chain of Change Managers. You had to file a ticket filling a long form describing motivations, services impacted, testing strategy, contact details, and so on. Lack of trust is really expensive. At the contrary, teams and organisations where people trust each other work like magic.

Communication mirrors code quality

We all know Conway’s law: “any piece of software reflects the organisational structure that produced it.”. In the same way, communications patterns between people affects the quality of the software. After 6 months working on a greenfield project I realised I could link all the areas with major technical debt to some unsolved personal conflicts in the team.^[7] On the positive side, a team where everyone feels safe and is free to communicate, where team mates trust and respect each other, will refactor code more freely, come to sound judgments in a constructive way, and will be more open to feedback instead of worrying about defending egos.

Happy developers produce great code

It’s without saying that when we feel passionate about what we do, that’s when we perform at our best. Still, we forget about it when we have to take technical and organisational decisions. Learning new skills, earning our team mates respect, having an impact on our product, feeling that our ideas are taken into account, these are all things that increase our daily happiness.^[8]

Conclusions

I hope you enjoyed reading this series of articles. If you felt inspired and you’d like to make some changes in your way of working, just try to consider the human factor in your daily decisions, as a developer or as leader. A small shift in perspective could make all the difference in the long term and lead to new discoveries on your own journey.

Thanks for following these posts, and have happy holidays.

Notes

 
1. If you are interested in the topic of scientific studies in software engineering I can recommend this book: Making Software: What Really Works, and Why We Believe It. It’s a collection of researches about topics such as TDD, Pair Programming, high level languages… Unfortunately the findings are often inconclusive.
 

2. I’ve written the whole story in 4 blog posts: a dysfunctional team, change, clean slate and finale. The post you are currently reading is somehow the moral of the story.
 

3. Processes and tools are amazing. In my story I’ve recounted many times when a change in team dynamics was supported by a change in process or adoption of new tools. But the point is that they are just instruments. The “why” behind them is much more important.
 

4. I still remember an amazing talk by Dan North at an Agile conference I was attending three years ago. “Individuals and interactions over processes and tools” was one of the core principles in the Agile Manifesto, but 10 years later the Agile community seems to have forgotten. Some would argue that processes and tools are easier to sell and turn into products, therefore more interesting for consultancies.
 

5. I’ve written about it in my own story, how all the internal conflicts reduced productivity and morale, and how we changed.
 

6. A different hierarchy of values is for instance what animate the debate around the software craftsmanship movement.
 

7. I wish we had better tools for static code analysis. I can imagine the kind of errors and warnings I’d like to see: line 28 on Product class was written with an high amount of boredom; the module ShoppingCartSerialiser was written with high level of confusions because of lack of communication with stakeholders; the method filter_results on the OrdersCollection class contains too much of “I-don-t-care-because-I-am-a-micromanaged-contractor”
 

8. A brilliant article I highly recommend about technical choices and their impact on values: What technology should my startup use?.

And here we are, looking at the gran finale of this (now) four-part software development story.

We left our team in the middle of it’s defining challenge, facing doubts and concerns.

Now, your first instinctive reaction – if you find yourself in a similar condition – is denial. It’s a natural defence mechanism.

– There are no problems! They are just over reacting! Besides, it all looks easy to me: you just need to do this and that, and that’s it…

Why do we do that? We don’t want to admit there are issues. We invested much of our ego in a project, and when problems arise, we ignore them. The bigger the problems, the more we tend to ignore them. And we are all walking together our death march.

It takes some skills to actually stop, and be honest with ourselves. Stop and listen.

What helped me to acknowledge it was my focus on listening and respecting my team’s opinion.

What helped us to work it out and solve it, was our unwritten (but practiced) belief in respecting and eliciting each other’s feedback.

So we made a plan, we plotted some practical actions.

To shed some light on the root cause of those bugs we introduced an extensive logging solution, that tracked everything happening on the HTML 5 app, storing it in the device storage and syncing it back to server for further analysis.

Funky bugs

What we found was quite surprising. Some of those most obscure bugs where only happening using a mobile connection and not over WiFi.

We looked at the extensive logs, and we found some weird error messages, that were definitely not generated by our code.

It turned out that some network operators, to optimise user’s bandwidth, re-scale the images contained in a web page, and then inject some custom JavaScript at the bottom of the HTML in order to serve the full-quality version only when the user taps on them.

That piece of random JavaScript written 8 years ago, totally inadequate to modern single-page applications, was hijacking our event handlers and throwing odd errors.

The elevator test

Our testers did an amazing job in identifying this and other potential bugs.

In contrast with the situation we found at the very beginning of this story, this time the collaboration between developers and testers really payed off.

As developers, instead of rejecting the concerns of our testers that couldn’t be proved, we built them tools that allowed them to automatically record what was happening and easily report it.

As for them, they used their dedication and creativity to come with new clever ways of testing.

That’s how we invented the SouthWest Train commute test (aka: what happens to your mobile app with an intermittent connection) and the elevator test.

Taking the elevator from our second floor to ground zero, facing an internal corner of the compartment, was a very accurate and reliable way to cut all 3G signal.

These tests raised a lot of questions, and highlighted important assumptions we missed. Is you app able to properly detect your connectivity status? Is it blowing out in the middle of a server requests? Is it able to recover from that?

So, you could sometimes spot a developer and a tester, going up and down on the elevator, until some obscure bug wasn’t ruled out…

Agility

All our technical choices and process decisions were oriented towards flexibility and adaptability: we choose an HTML5 app, so that changing device and operating system would not be an issue, we choose REST protocols and a loosely typed data format such as JSON, we choose a NO-SQL database which allowed to quickly enhance our data, we choose Ruby and JavaScript as dynamic programming languages, we choose a cloud system which let us delay performance concerns with super-easy scalability, and we wrapped everything in robust but loose test suites, to be able to constantly and safely refactor and reshape our code.

Towards the end of our development, when the user trial was approaching, these choices really payed off. As we became more confident, our velocity increased. Our business sponsors were noticeably satisfied by the pace of our delivery.

We used retrospectives and demo to get fast feedback and steer the direction our efforts, and – as lubricant – we encouraged open communication, and we relied on mutual trust.

I happened to witness a brilliant example of that: after a demo which raised some discussions, our two business owners stopped for a chat with one of the developers. Looking at the screen, they were able to quickly take a better decision, implement it, and commit and deploy the new feature. They were happily shocked. You must know they were used to have long discussions with business analysts and technical architects before a change could even be scheduled by a project manager, and then wait for weeks, and sometimes get something completely different from what they were looking for.

Good and open communication was really the magic that kept the engine working so well, both internal communication between developers, testers and our business analyst, and external communication, establishing great relationships with he DevOps teams, our department technical directors, and our business sponsors and project manager.

The last obstacle

We finally launched our user trial, with 20 sales agents using our iPad application in their daily job. We built them an easy way to report their feedback, and we put in place analytics to track the outcome.

The results were encouraging. They all loved it.

No bugs ever reached our users, except… except one user started to complain about losing all his data.

For better network and battery efficiency, and to keep functioning in areas without 3G connections, our application was storing a lot of data in an offline storage and synchronising this data on-demand.

Losing that data was a huge problem. Luckily no sales were lost, but all the logs about the daily activity – which meant so much for the agents, their managers and for our understanding of the success or failure of the experiment – were gone.

As an isolated report, we blamed it on the agent (he may had accidentally cleared the offline storage after all).
But when a second agent reported the same issue, our worries become real.

How was that possible? We tested the application for months, both manually and automatically, on different networks and connections, using the same physical device used by the field agents, and we never ever found a similar problem.

Our attempts to reproduce the issue, involving a lot of creativity and hard work, kept failing.

Finally, after more research, hacking devices, and inspecting the internals, we discovered the cause of the issue.

Months before our launch, Apple introduced a change in the way HTML5 applications local storage was treated by iOS. When the operating system decided to run a “garbage collection” – because of low memory or as part of a routinely clean-up – it could effectively wipe out that data. Local storage for HTML5 applications was now treated as temporary.

The only reliable solution, guess what, involved adding an extra new technology to our stack: a native application wrapper for iOS, written in ObjectiveC. As you may imagine at this stage, learning a new technology couldn’t really do more harm than galvanising our team. Such are the benefits of working with a team like that.

We quickly built a prototype that proved our solution, and with the support of native developers from the Mobile department, we refined it and released it to our agents. The bug was squashed.

Mission accomplished

So, as I promised you four blog posts ago, there is a happy ending. And here it is. : )

At the end of our user trial our business sponsors were hugely satisfied, so much that they tried do assign us other parts of a bigger project. We delivered much more than what we promised, by listening and constantly adapting to their requirements.

Our agents and final users loved the application and loved being involved in it’s development.

We pioneered new technologies, we showcased them to the rest of the department, making our technical directors happy.

We went from being the cinderella of the department, to the raising star.

What happened after that to our team, the hero of our story?

Soon after, as a result of some high level restructuring, the team was moved to another department and bound to merge with another one.

Somehow, we all felt that our experience as a team was over, and in few months most of us went looking for new adventures.

And so, the story ends, with our heroes walking towards a sunset.

But before closing the curtain, I’d like to spend a final post on this topic.

So, if you had the patience to follow it up until now, there is an extra bonus in preparation…

Soon… : )

I always found updating my CV a painful, but necessary process.

I’ve decided to rewrite it in a new way because I needed to:

• make the update process faster (going back to be a freelance means I have shorter gigs)
• focus more on the content and leave aesthetic concerns in the background (I used to write my CV with Adobe Illustrator…)
• manage multiple versions (I needed a version focused on my developer experience, and another version more focused on the team leadership skills)

There is a common saying in the Agile community : if it hurts, do it more often. That’s the spirit behind, for instance, having more frequent releases. By doing it more often you are guided to make it easier.

So I started to look for ways that would allow me to update my CV often, and I came out with a solution based on Markdown.

The solution

Markdown CV is basically just a script and a template I use to generate nicely formatted PDFs out of Markdown syntax.

• here is the code (feel free to fork): github.com/bitlyfied/markdown-cv
• this is an example of the output: name-surname-cv.pdf
• and this is how the Markdown source looks like

The process is fairly simple.

• one file written in Markdown contains all the content
• the file is converted to HTML using github-markdown Ruby gem
• a basic string replacement adds a tiny extension to the language (read further down)
• the HTML content is injected inside an HTML/CSS template and saved on the build output folder
• wkhtmltopdf is used to convert the HTML file to a PDF file

Augmented Markdown

Why Markdown? For two reasons:

• Markdown helps me focus on the content, clearly separating the design
• being simple text, versioning and branching (using Git) is easy and effective

However, Markdown has also a very limited set of features.
While converting my old CV to Markdown I realized I needed something more.
Using standard Markdown I couldn’t find a way to escape from the boring single-column layout.

So while trying to remain true to the original spirit, I’ve added a new syntax that allows me to identify blocks of content.

It’s as simple as this:

## Here is a title

[aside]

## Here is another title

[/aside]

This is going to be rendered as:

<h2>Here is a title</h2>

<div class="aside">
    <h2>Here is another title</h2>
</div>

Using a unique identifier in square brackets at the beginning of the line I can now identify a block of content, that will be rendered as a </div> tag with the same class name as the identifier.

I can now style that block as I need. In the example the block is floated to the right of the page.

Note how ensuring that these identifiers are semantic and not stylistic is now up to the writer.

PDF Pages and Web Pages

One interesting challenge I had to face was ensuring that a free-flow markup language such as Markdown could be nicely rendered in a paged medium.

CSS2 have a lot of useful new functionalities that allow some tuning of how the content should be split between pages.

Unfortunately I couldn’t make the @page CSS directive work with wkhtmltopdf, but I could still rely on CSS properties page-break-* to limit or enforce page breaking.

After some failed experiments I settled for a semi-automatic solution. This single CSS property is the key:

p, li, .block, .aside{
    page-break-inside:avoid;
}

First of all, this is forcing wkhtmltopdf to never break a page in the middle of a <p> or <li> tag.

But it’s also applying the same rule to a custom class “block”. This class is part of a div, generated using the extended Markdown syntax.

[block]

# This title...
## ...and this subtitle...
...and this paragraph, are always going to be rendered on the same page, as part of a consistent block of content.

[/block] 

This trick is a compromise. Using a bit of extra semantic we are still ensuring that the Markdown doesn’t have to programmatically define page break, but at the same time we are guiding the HTML/CSS engine in rendering blocks of contents together.

Usage

Feel free to fork the Github repo and experiment with it.
Check the README.md file for more details.

Starting a new project – as a Tech Lead – I wish I had a checklist that reminded me all the important aspects to consider.

This is that checklist.

I’ve recently started reading Code Complete 2nd Edition, and I found the chapter about Architecture Prerequisites interesting, but out of date with the current development trends. So I thought about taking inspiration from it, adapting some of the advices to more Agile practices and narrowing it down to web development.

This list is not necessarily complete, nor mandatory, but it’s intended to be used as a memo.

Some of these issues naturally need to be addressed at the beginning, but most of them could be specified during the development cycle, depending on the delivery strategy.

Re-use VS Build

First and foremost: have you considered re-using pre existing solutions? If so, justify why (i.e. an open source framework, an existing library, a service already available, etc.).

Componentization

Modern architecture tends to favor small, independent web-services instead of monolithic applications. Have you defined the components in which your app could be split?

If you have the flexibility to do so, this doesn’t need to be defined at the beginning of the project. I’ve noticed for instance that using a cloud infrastructure allows a more flexible, evolutionary architecture. If your hosting is less dynamic it’s important you figure it out upfront, or the cost of change is going to be too high.

Data organization

What databases are going to be used, and why? Particular care should be put in identifying relationships between data. This could be done by analysing important use cases generated from the core business requirements.

Integration

No application is an island nowadays. Clarify the point of integration with all other internal applications (business core apps), or external (social networks, payment services, web APIs etc.). What protocols should be used? How will the integration been assessed?

I like the architectural principle of building “hard shells and soft cores”. The shell is the interface that the application expose, the core is the actual code. Focus should be put in specifying this interfaces and how they communicate.

Testing strategy

I believe thinking about the testing and stubbing strategy is really important at the beginning of a project. In the same way as TDD/BDD practices inform the design of the code, defining how the whole system will be tested generates useful insights on the architecture itself.

So, try to identify what kind of automation test suites will be necessary, and how and where the point of integration will be stubbed.

For instance: test JavaScript front-end in isolation using Mocha, test the Ruby back-end with RSpec, functional BDD acceptance tests using Selenium to exercise the whole app – except for the unstable dependencies. Etc.

Environments and path-to-production

How many environments are you going to need? How many can you budget? Think about: dev and QA environments, integration environment, production-like environment for load test, offline/online environment separation, disaster recovery and data-center replication..

Error handling

I’ve never done this upfront, but after reading it on Code Complete 2nd Edition I realized how important it is, and how much headache it could save. Basically, try to define how errors should be handled. See if you can define a common pattern for generic error scenarios. How will this errors manifest on the user interface? How will they propagate through your code? Do your back-end and front-end frameworks already have an error-catching strategy?

On a similar topic: define a logs strategy. How much you application will need to log? Where will the logs be stored? I personally agree with what Hugh Williams (eBay) said during a panel about scalability at 2012 PHP UK Conference: log everything you can.

Content management

How will the client manage the content? Do they need the capability to update content without doing a deployment? If so, do they need a user friendly interface and a proper CMS solution? Also, what about internationalisation? Have you thought about how this will affect your testing strategy?

Security

Have the security requirements been specified? Have a solution been proposed? How will these requirements be tested? What about data protection and PCI requirements?

Availability and performance

Have you discussed the availability requirements with the business? Are they just random numbers or have they a business meaning? How are you planning to do load testing and performance testing? Also, how are you going to monitor the availability? Start defining hooks for your monitoring tools and availability metrics.

Robustness and overengineering

What level of robustness your application needs? Is it going to be a medical surgery software where a minimal error may be fatal, or is it going to be a content-based website? Is this a code business application or is it a restricted prototype? I found defining the robustness upfront really usefull, because a lot of great developers tend to build the best robustness possible out of pride and professionality, but sometimes it may not be cost-effective.

Changeability

Can you identify what areas are more likely to change? If so, can you define a strategy to make change easier? For instance, if a specific data section is likely to change, using unstructured documents-based solution like MongoDB could make it easier.

Can you identify other “strategies to delay commitment”? What about using configuration files and features flags?

Hi everybody. So this is my first post. After more than 3 years I’m finally back writing a blog. My previous blog is still on-line. If you are curious, here it is: http://www.maverick.it/en/

Why WordPress.com? I admit it was a tough decision. My first plan was to build a custom blog engine using Node.JS and hosted on Heroku. Then I realised I would have to duplicate a lot of things I could get for free. I also like the fact that using a ready-made solution force me to focus on the contents and less on the technical details.

My plan is to use this blog to publish my technical discoveries and my thoughts about web development and technical team leadership.

So here we are. Let’s begin.