Make it New

A blog about everything and anything we care about. Mostly topics related to consultancy and IT.

[makeitnewio]

Why go Agile?

During a recent meetup Martine Devos spoke about the Agile Raspberry Jam. This is an adoption from The Secrets of Consulting by Jerry Weinberg where he offers us his Law of Raspberry Jam.

The wider you spread it, the thinner it gets.

Martine also mentioned that we have come to the point where the early majority, according to Moore's technology adoption lifecycle, are "going" Agile.

One concerning trend among the early majority adopters is the approach to use "Best Practices". This is a very dangerous move in most cases.

If we take a quick look at the Cynefin framework to try and understand the nature of the work we are dealing with.

Without going into too much detail about the Cynefin framework, we can see, by looking at the image above, that "Best Practices" can be used when dealing with Obvious tasks or issues.

But the area where Agile shines is to help bring work from Complex to Complicated, and sometimes to Obvious. This doesn't happen by itself just because you claim to be agile and adopt agile "Best Practices". Behind every success story in Agile is a long journey. This journey will be full of trial and error. You need to experiment to find out what works in your UNIQUE situation.

This brings us to the reason WHY you should go Agile. Normally I have a coaching approach where I let the coachee reach the answer themselves. But in this case I'm going to tell you.

The reason you go Agile is to Maximize Learning!

If you claim that you don't need to maximize learning in your company because you only want to increase throughput/productivity/X/Y/whatever/... Then you have misunderstood the whole reason behind Agile and you should rethink your decision.

If you don't make sure to value the underlying principle to Maximize Learning you will never reap the benefits of Agile.

If you compare your company to a person walking. You are pretty good at what you do. You have no problem moving forward and getting to your destination. But you have seen others on a bicycle and they get to their destination much faster than you do. So you get a bike. The only thing is, you don't know how to ride a bike. Also, the certified bike salesperson who sold you the bike didn't include any pedals. Well, this is nothing to worry about now - you say. You get on your bike and have at it! You manage to propel yourself by kicking with your feet and you fall over a lot. But eventually you will get the hang of it and start to see the improvements over walking. But you still don't have any pedals, or know what they are for.

The same way the pedals are core components of riding a bike, is the underlying principle to Maximize Learning a core component of Agile.

About the author - Joakim Sahlberg is an Agile Coach working for Netlight Consulting in London. He has a strong opinion that Agile is not something you do, it’s a state of mind. If you are looking to change the way an organisation does software development, you have to change the way it thinks about software development.

[makeitnewio]

Gamification - Do you need an internal loyalty program to retain your employees?

Gamification is a word I hear all around currently, and I like it. For me personally taking everything far too serious gamification is a great tool to stay in balance with my stress. Hopefully it will help me last a few more years :-).

In services I use I also like gamification, who doesn't want a fun user experience showing there is some thinking and depth behind. Fun doesn't mean non-professional as it used to when I was a kid - meeting greyish robot-like-people at the bank or watching the news.

But what about your own company, could it gain from introducing a little more gamification? Will it make people more engaged and involved?

Currently I hear about several companies introducing loyalty programs for their employees. As an employee you will earn loyalty points based on your actions and your result (I assume it's based on your team/group result so it doesn't make a nursery for individualism on behalf of creating together). I guess it will be used both as a carrot to change behavior as well as strengthening correct behaviour by rewarding it. Your loyalty points you can then convert to real value merchandises or services in the company internal web shop.

I can't really make up my mind if I like it or not. I like the fact that you challenge what is "normal" and that you care about your employees. I like the fact that you can promote and reward good behaviour. I love how you promote role models within your organisation and cement your values around those. That's how you build your culture - remember a company doesn't have values and culture, people do.

But what makes me hesitant is how you reward and when...and what you reward with. The risk I see is that you’re not getting the healthy incentives you’re hoping for if you don’t think it trough, so please do. Wouldn't it be better if the reward was made by the individual herself, feeling good about doing something great, and by the people close around? It doesn't really scale if somebody at top (now I'm guessing) do have to come up with anything and everything to award and how much it is worth. And what does that signal about everything that's not centrally set as "rewarding", isn't that worth anything? Should the responsible person and team not take care of those things? And who will be the judge deciding who deserves which reward? Will it be fair for all or will the situations of injustice be the ones remembered?

I just picture myself, raising up my children, promising them candy every time they do what I ask them. Yes they will probably be good children doing what I ask them, ie behave well (if they don't get too crazy from all the sugar). Or will they only learn about the rewarding game and not become healthy thinking and questioning human beings? Yes, most likely they will adapt to the system, do whatever it takes to get candy when they feel like it but never do anything else. Own responsibility?, hmm what is that?

Don't get me wrong, I love games and gamification but maybe we're simplifying things a little too much believing we can apply it directly on (work)life as a whole. For isolated areas I really like the idea as it brings an extra dimension of joy and meaning to many. Like social networks it works fine. To many it brings an extra level of excitement and meaningfulness counting your likes and your friends. But running your life only based on drivers like KPIs of likes, friends and followers will probably not be the final answer to happiness, or? Life as I know it is more complex than that.

As I said I'm not really sure what I think. I love to follow the experiment of internal loyalty programs as just that, an experiment. Implemented correcly it might be a very good thing, but what I'm saying is I see risks. I love change, I think we in our modern companies need change over and over again to make sure we challenge ourselves and keep on growing professionally and personally. I love to try any ideas that come from employees for employees since they, me, we, are our greatest and only real asset. We all, as employees, have and share the responsibility to make sure work is fun. I have the responsibility to make sure I'm passionate about what I do. Just as in the life outside work (I think it's called free time) I'm sure you're taking responsibility. I'm sure you make sure to do the things you don't like as quick as possible and spend the rest of your time on things you do like, things that you think are fun or make you feel good. Complaining? - to whom and for what reason? Of course it's good to drain your feelings to friends now and then, but complaining doesn't do any real good. And same goes for work life, I believe. Complaining I see as a sign of you failing in taking responsibility, for some reason. And it's good to understand why and do something about it - that's taking responsibility.

So, do you need to have an internal loyalty program to retain your employees? Maybe it's a good idea but please think it trough with your employees and together understand what you want to achieve. If you think an internal loyalty program is the only way to retain your employees, unfortunately I think you're in big trouble.

Anyhow, I'm very interested to see the outcome so please share your experience if you have some.

Do I think it is important to keep employees involved and engaged - 100% yes. Do I like sharing company profit in any way - absolutely. Do I think people should have fun at work - where can I sign up?

What’s your thoughts, how do you design and introduce gamification within your company to increas engagement, committment, passion and keep all healthy incentives? What's your experience of internal loyalty programs?

...............................................................................

After going arond for a day not getting the post out of my head I came up with the following idea of how to design a gamification model that might drive healty incentives and good behaviour.

What if all colleagues around you dynamically award each other points whenever they feel like you’re doing something good, something bringing value to them or others. Like a natural feedback thingie, just like you say tanks for helping or great work – may I call it “microrewarding”.

If you are engaged, if you show you care, if you take responsibility, if you have a good perspective bringing value around, if you have a big followership, if you are a natural go-to person then you will earn your points. The great thing with this model is that you don’t need a judge nor referee for the game. It will be self-managed, how life works already.

This model of gamification will probably help you better identify valuable people not only seeing the obvious ones knowing the right people or the ones in your closest network.

Scalable? Oh yes, this model will scale to infinity.

But what about the reward? I think it would be enough with the honor of being seen and promoted role model. Since the points you have will (should) reflect your contributed company value, it’s of great input during your annual salary review process. Doing a normal 360 tend to make us focus on the past month or so as that’s what we humans have fresh in mind. But with this gamification model, which more or less is a live ongoing 360, the whole period will count equally important over 6 or 12 months.

Of course the model will come with challenges; there are no shortcuts in building great companies - it’s all about hard work. In this case a lot of hard work must be invested in setting the guiding principles for how to behave, setting the culture. When and what to reward and when not to. How to treat all equal and give all the same equal opportunity despite gender, religion, skin color or culture.

Dangers? Actually, as we see with gaming, the constant rewarding and hunt for the next reward after that, might not be very healthy. For some it might become the uncontrollable heroine. But for the majority I think it would be a very interesting experiment to be part of. And I think it really will get the dialog and communication going about values, about what is good behavior and not. About how to spend your time in the best possible way. About how to take responsibility and being a role model. About how to build the great company of tomorrow.

What a an exciting and fun experiment to follow :-)

About the author

I’m Mandus Engman. I’m Partner at Netlight, I’m a Genuine Consultant, I’m an entrepreneur, I’m a father and I’m a believer. I meet many companies in different situations, different challenges and different opportunities, I meet the people. I’m a believer in the meaning I believe that together we can really make a difference. Together we can really achieve something and make the digitial future and the world a better place

Folllow me on twitter: mandus_engman

[makeitnewio]

Is Microservices the future of all architectures? Is it "the" silver bullet for any company with a business critical IT?

    We all start there, with the famous Monolith Architecture. Why? Because it’s easy, it’s fast, it suits our needs just fine. Remember the first rule when distributing your systems – “Do NOT distribute your systems”, until you need it, then “Do NOT distribute your systems”, unless you really really really need it. So the Monolith is the perfect start for any start-up and can suit your need for a very long time, potentially forever.

So why bother understanding what Microservices is all about?

    There might come a day, when you feel you grow out of your Monolith. The size of your organization has grown quite a lot, your dev department is getting bigger, perhaps dev centers separated geographically. All you know is that growth is the only thing that will stay stable for the near future. Sooner or later I think you will start to see the typical signs of you outgrowing your Monolith (if not – congratulations, please tell me and the world how you did it); You start to realize that small changes within your intercoupled Monolith impact areas you didn’t think of, leading to costly incidents. Things are getting complex due to all dependencies. KISS becomes harder.

You realize you want to, you need to be agile, but deployment is hindering you as it takes too long time and too much effort to deploy. You can’t deploy the small parts you updated in isolation so you have to do the whole thing.

You realize there’s legacy parts of your system you don’t dare to touch, no one does, so you build around. Developing new features (business or tech) will be more and more expensive since the only compensation for you systems growing complexity is increased quality. And we all know how expensive increased quality is, both for dev in itself but also the additional QA work required.

Eventually things will in a larger extent break and you will spend more and more time on failure demand, cleaning up the mess, than on value demand, developing your business. By now your REAL problems are likely to start show and you will probably start see the frustration around. Dev will most likely get a hit on her self-confidence, the pressure from the organization will grow and the joy you used to have will be jeopardized. From the business perspective one start see things taking longer time and Business people will have to fight more and more to get their things into the three-months-roadmap. They will most likely start interfering into dev work, dev processes and dev decisions like never before. Things like mistrust, control, processes will start becoming the words on peoples lips.

Sadly this will often lead to growing bureaucracy and hierarchy; your organization will most likely become more top-driven and politics and individualism become a fact.

What it does to your previously so lively and joyful dev teams? I think it will have a great impact on the inspiration, energy and commitment of your dev teams – hurting the innovation and engagement. Unfortunately it will risk your most driven tech people, seeking new adventures.

In all together you start to realize that your baby that used to be so small and sweet, over the years has grown and become a monster, something like the famous “big ball of mud”.

So what to do, what’s the cure? Which architectural solution to go for?

    It all depends on what you want to achieve and that’s where you need to start. Telling by the symptoms above I assume what you want to achieve, I would, is for your dev department to continue its joyful and innovation-driven journey together with the rest of the organization and business. Then I believe what you need the most are;

Independent scalability

Independent failures

Independent deployment

These three qualities will provide wonderful things since it pulls out dependencies and by that removes complexity. Dev teams can again focus in isolated areas; scale, handle quality, handle failures and deploy independently from all other teams. So which architectural solution to go for? Use anyone as long as you fulfill the three qualities.

What about Microservices, could that be the solution for my organisation?

    Yes, Microservices will definetly help you support the three qualities; Independent scalability; Independent failures; Independent deployment. But Microservices will as well support you creating a new “big ball of mud”.

To me Microservices is a mindset more than anything else. Initially, being new to Microservices, you will make mistakes, no question about it, but if you’re eager to success, if you use your architect experience well in combination with a great portion of common sense and continuously seek new competence and experience from others – you have a promising and exciting future in front of you, and full of hard work. The main fundamental capabilities of Microservices and the resons to go for Microservices according to me are;

The super qualities - support of the three qualities that are so crucial for successful long-term business critical IT development; Independent scalability, Independent failures and Independet deployment.

Burn it to the ground (including your darlings), over and over again – to me one of the most important and valuable mindset of Microservices is to avoid making anything too big or beloved to mentally be prepared to burn it to the ground, at any time.

Remember the old scary legacy code in the Monolith that no one dare to touch but would build around? In the world of Microservices just burn it to the ground and rebuild it.

In the Monolith when introducing a new feature you tend to bring in the generic perspective too early, just in case because you know the code will stay around. In the world of Microservices you’re permitted to have a much more healthy mindset; don’t bring in the generic perspective (that will add complexity and extra code to maintain, ie cost) until you really need it. When you really need it, you have the option to expand an existing Microservice or to burn it to the ground and rebuild.

In our agile world the only thing we know for sure is that things will change. In the world of Microservices you can really embrace change. When the basic requirement change too much we all know it’s better and more cost effective to rebuild from a clean slate but in the Monolith you don’t always get that option, it’s too risky and costly. In the world of Microservices - burn to the ground and rebuild!

New to Microservices? Of course your services and structure will suck initially. A year later you and your organization will know so much more. Burn to the ground and rebuild!

Just knowing your Microservice can be burned to the ground and rebuilt makes you a better developer and architect. You may focus on what is important then and there. You don’t have to spend too much time weighing pros and cons back and forth regarding patterns, frameworks and tools. In the Monolith you tend to build with high quality all the time, in your Microservice landscape you don’t have to, depending of what you need to achieve.* A single Microservice is the perfect (in theory) container of coherent logic. An isolated component or system doing one thing and that thing very well.

Last words for now…

    Yes, Microsoft provides great powers and used right it could be the answer for many companies, which I see already looking at our (Netlight’s) clients. In the post, however, we haven’t talked that much about the pitfalls, which of course are many (spared for a later post, perhaps). But we should all understand that transforming your Monolith into Microservices means an enormous amount of work and something your entire organization must be involved and committed to. And be careful, designing your Microservices too small, will just move your current complexity into your integration layer. Designing them too big will divide your huge Monolith into a couple of smaller ones, still Monoliths. There is no such thing as the correct size of a Microservice, don’t believe anyone saying there is, and of course the number of lines of code is a very bad metric. What I like is the mindset that any of your Microservices should be rebuildable in roughly a month of time. Then you will still be able to burn it to the ground and rebuild when its time has come. At the speed technology, knowledge and organisations develops today, after 2-5 years I bet the majority of your complete Microservice landscape will have been rewritten. That’s healthy evolution to keep you a competitive player and a healthy company.

What’s your experience of Microservices and Microservice Transformations?

About the author

I’m Mandus Engman. I’m Partner at Netlight, I’m a Genuine Consultant, I’m an entrepreneur, I’m a father and I’m a believer. I meet many different companies in different situations, different challenges and different opportunities, I meet the people. And I’m a believer in that I believe that together we can really make a difference. Together we can really achieve something.

My purpose and passion in life is kind of three folded;

I want to be part of creating the digital future we all live in – I love technology...in combination with business

I want to find talented people and companies eager to find a purpose themselves. I want to help them reach their full potential and I want to create magic together with them.

I want to show the world that the future of high-value service companies should be based on trusting the individual and self-management rather than hierarchy and individualism.

And remember - Sharing is always caring…

Folllow me on twitter: mandus_engman

[makeitnewio]

Making XDomainRequests play nice with Node/express/body-parser

I recently spent a couple of days working with XDomainRequests. This is the legacy technology that allow you to do cross origin requests (CORS) on Internet Explorer 8 and 9. To explain CORS further: if you have a web app available through “myfirstdomain.com” and that web app, once it is loaded in the browser, sends a request to an API that is available on “myseconddomain.com”, that is CORS. Requests between different domains.

Now, this blogs title is “makeitnew.io”, and I will be the first to admit that this posts relevance might be missing. But as it took me a really long time to find a solution for this in my network, and on Google, I feel that I need to write this post to help the next person, implementing legacy browser support for his REST API, to get this problem solved more quickly.

The Problem

My issue manifested itself after deploying a piece of client side JavaScript that supported XDomainRequests to all our clients. Suddenly alerts about a huge spike in 400 errors filled our system health channel on slack. The number of errors, and the lack of decrease in HTTP response 200, makes it relatively clear that most of the extra traffic we were expecting to get from rolling out support for IE8 and IE9 are all coming in as errors.

I immediately rolled back the change. After the back end looks healthy again, I immediately started looking for reasons why this would happen. Former Microsoft employee Eric Law has written probably the most comprehensible guide to XDomainRequests, and I read through it with a looking glass to find possible explanations.

The first likely culprit is that XDomainRequests are supposed to send requests with the content-type “text/plain” in the header. Yes, I missed the note in Eric Law’s post saying that as of 2014 no content-type seems to be sent. So anyways, I open Postman and start sending requests with the culprit content-type and get 400s back. Time for a pull request on our collector service.

So after setting up everything I need to test locally, I add support for body-parser to parse text/plain on our Node.js / Express back end collection service. Still just 400 back. WAT.

So I am using Internet Explorer 11 in IE9 emulation mode for sending the requests. And the request bodies being sent appear empty. I enable some logging in the console. And, no, the request body is not at all empty. Weirdness is going on here. I get some logging going on my local fork of the collection service. And yes, the requests are in fact empty except for the header.

At this point I am confused and I start reaching out to both my network and Google to figure out if others have experienced the same problem. And there is not much help to be had. I find some colleagues that have experienced something similar and have solved it by creating a proxy for requests with the same domain as their service. Allowing them to use XmlHttpRequests in old Internet Explorer instead. As the script I am making is running across a lot of different domains that I do not control, this is not an alternative. So I keep on Googling.

My breakthrough comes when a colleague suggests that I use PyProxy. After firing up Wireshark (because that was what I had installed) and sending some packages, I discover two things. First, that there are infact a request body that looks healthy. And secondly that the content-type is missing.

The Solution

After realising the issue was actually the content-type missing, I was able to find a package called “express-content-type-override”. And while it was not perfect, it was enough to fix the problem for my case.

What the aforementioned package lacks to account for, is that the charset also goes in the content-type. That caused some initial problems that was quick to find and fix.

I also submitted a pull request for this: https://github.com/rbartoli/express-content-type-override/pull/1

What is important is that the content type is checked and modified before bodyParser is added to as middleware.

Example

This code is all in the server.js file. Which is where the routing happens in the mentioned application.

This is put in the top of the file, together with the rest of the required packages.

var contentTypeOverride = require('express-content-type-override');

The middleware is applied right before the routing happens:

// Handle XDomainRequests coming in without content-type header. app.use('/api/send', contentTypeOverride({ contentType: 'application/json', charset: 'utf-8' })); var apiSendRouter = require('./routes/api-send'); app.use('/api/send', apiSendRouter);

Parsing of the body happens inside the required file for the path (./routes/api-send)

About the author

Magnus Skaalsveen is a consultant in Netlight Consulting. He enjoys working with front end development and user experience.

[makeitnewio]

What does a User Experience specialist do?

The other day I was contacted by Linnea, a student who had just started an interaction design education here in Stockholm. She wanted a better understanding of what was expected from a professional User Experience (UX) designer and if I had any tips on what to think about throughout her education. Her questions made me think about my view on the role as a UX specialist and I hope that our conversation can be an inspiration for others to join the UX world. Here's what we talked about.

[Linnea]: What do you like the most with your work?

[Niklas]: In my work I'm striving to understand people's reactions and demands when they are presented to a digital service (I do UX for the web). It gives me great pleasure when this understanding can help the team to find clever solutions to the problems that people experience. Through the UX role I talk to a lot of people about the service which makes me involved in many parts of the service design.

[L:] What does an ordinary day look like for you?

[N:] I work in an agile development team and when the team is assigned to solve a task or a problem we do it together in a design studio - a workshop where we try to find good solutions to the task. I'm usually facilitating this workshop and the output we get is hand drawn wireframes of how we think that the web site should look and feel. Once we have wireframes, I refine them to prototypes together with developers and graphic designers and either run usability tests, or execute A/B-tests on the live site. This way we quickly get user feedback on our ideas and can make further adjustments if needed.

Another part of my job is to do statistical analysis of the site, in order to understand what the users are really doing and to identify parts of the site with good or bad performance. This week we’re also running a web survey on the site in order to get input from real users.

A lot of my time is spent in discussions with the team, product owners, and stakeholders for us to understand the business goals and how we best can achieve them. That gives me a central role in the team which is a great motivator for me.

That gives me a central role in the team which is a great motivator for me.

[L:] Wow, that’s a lot. But where in the process are you involved?

[N:] Right now I’m working on a service that is out on the market. We are constantly working on new concepts and improving the service even more. In general I think it is important to have a UX specialist throughout the whole life cycle of the service. A digital service is always a living product. The challenges are different if the service is on the market, compared to a new business idea. But there is always room for creative ideas.

[L:] What background does you and your colleagues have?

[N:] We actually have different backgrounds. Some come from technical educations with focus on interaction design and others have studied at design educations, or interaction design educations (like yours). But there are also those that have learned the craft during their professional career.

[L:] What are the demands in the professional life and what competences are expected? Maybe a strange question, but I think about subjects that are not part of most educations within the field. Is graphical design and programming languages something I should look at?

[N:] The demand varies from case to case. As you understand from my answer above there are many competences that go into UX. Methods for describing use cases, conduct usability tests, lead workshops and build prototypes are essential to have in your toolbox. For a successful service, the whole team needs to be  involved in the UX work and you can add value by having a broad understanding of the involved competence areas, spiced with what you are passionate about. Whether it be programming (mainly front-end programming, like html, css and javascript), graphic design, analytics, or business analysis. Follow your own compass here and make sure to enjoy the courses you take!

However, what many educations miss out on is the understanding of business goals and market analysis.

[L:] What do you mean?

[N:] The role of a UX specialist is to fulfill business goals through a positive user experience. Terms like conversion and conversion optimization and A/B-testing are rarely mentioned at universities.

The role of a UX specialist is to fulfill business goals through a positive user experience.

[L:] What’s your take on the market for UX-designers or specialists? Will there be a job for me when I’m done?

[N:] User Experience methods and ideas have been around for a long time. But in the last couple of years the field UX has been growing tremendously fast and is now a natural part of all digital service design. The building blocks of creating a good user experience will never be outdated, but the trends and focus areas will change over time. Interaction design in combination with programming skills will make you highly competitive when you’re done with school.

Trends to look out for right now is web accessibility (how to make the web accessible for people with disabilities) and growth engineering or growth hacking. I suggest you look that up in your course programme or on google. Look for blogs, podcasts and meetups that cover these topics if you don't find it elsewhere. And good luck with your studies!

Comment

I found the dialogue with Linnea really interesting and engaging. In my profession I meet a lot of companies and people that all have their own idea about what UX is and what a UX person should or should not do. In my discussion with Linnea I deliberately left out specific methods and tools for interaction design. I think the most important task as a UX specialist is to drive the process so that you and your team (or company) better understand your users and the users’ experiences from using the service you are building. How you come across this understanding is up to you and your team. Another question that is often debated (in many cases rather intensely) is “What is good UX”. I claim that a good user experience goes way beyond designing a fast, intuitive and visually appealing digital service. And I will get back to that in later blog posts. Until then, have fun UXing.

About the author

Niklas Skaar is a consultant at Netlight Consulting. He is working as a user experience specialist and project manager.

[makeitnewio]

The UX of documentation - Introduction and readability

As an interaction designer and front end developer hybrid, working mainly with JavaScript middleware for the last months have made my IxD muscles tingle. The only part of my daily work that is actually utilized by users is my documentation. So I figured out that I should do some research on what users consider good documentation.

First off, let’s define documentation. For this blog post series, the definition will be documents meant to describe how to use an API, library or framework. It can also be documents describing functionality or development process for other developers that may or may not be working on the same project.

To get some data, I created a survey that I asked colleagues and friends that are developers to respond to and share with other developers. In total I got 104 responses.

I asked how good the developers felt at writing documentation. I also asked what they felt about the quality of documentation they found online.

The result shows that most developers feel their own documentation is not as good as what they found elsewhere.

Benefits of good documentation

One of the questions I asked was what the least enjoyable task a developer has to do on a daily basis is. Not surprising, documentation came out on top amongst the 104 respondents in my network.

Good documentation means less support, maybe also less meetings. Less support and meetings, means less context switching, which leads to more time to write code. According to the same survey, developing is the daily task that the same developers enjoy the most.

Good readability

Documentation can be quite text heavy, and therefore, we should make sure that the text is easy to read. I have collected some rules I feel is important for writing readable text:

#1 - Your grandmother is reading

Well, she will probably not be reading, but a lot of inexperienced developers, project managers and managers might. So use a simple language. Avoid abbreviations that are not widely known. Test your documentation on real users to see if they understand.

#2 - Break up the text

A trick I learned from journalists, is to break up long pieces of text. Use code blocks, headers and illustrations often to avoid huge blobs of text.

#3 - The right line length

There should not be more than 50 - 60 characters. If your lines is too long, it will be hard for the user to find the correct line to read next and keep overview of the text. Too short lines will force the reader to move his/her eyes back and forth a lot, leading to less relaxed reading. (source)

#4 - Chose a good font

Choosing the correct font is an art in itself. A google search should give you some good input. Find a simple font that is easy for you to read. A starting point for finding a good font could be “Verdana”.

#5 - Size and line height

The consensus when it comes to body text size these days seems to be 16px. Unless you have a good reason, stick with that.

The ideal line height depends on your font and font-size. Start with a line height that is 150% of your font size. Try increasing and decreasing and see how it affects you when reading the text. Eventually you will zero in on the perfect line height for your font and font size.

#6 - Use links and references

This might belong under navigation, but you should assume that users will not read your documentation from start to finnish. Assume that a lot of them will drop in at odd places after being referred from search engines. With this in mind, it is important to realise that the reader might not have all the needed context. You can help the user better understand by referencing or linking to subjects necessary to provide context. This is some work, but I know I would be happy when reading your documentation if you put that effort in.

Working around limitations

The survey shows that most developers document their code either as documentation blocks or inline documentation, closely followed by github and confluence/wikis.

This means that there might be limitations to what most developers can do to their fonts, line lengths and so on. So let us look at some language.

Services / Factories - This is the core collection of services which are used within the DI of your application.

https://docs.angularjs.org/api

So I dropped in to the first page of the first JavaScript framework I could think about. And without even scrolling I was able to find an abbreviation, “DI”, I did not understand. There was offered no explanation to what “DI” is above or in the near vicinity of these two mystical letters.

If you are a seasoned Angular developer, I assume you know everything that is to know about “DI” and that you find my lack of understanding silly. But as a JavaScript developer, that has not done much more than a couple of stranded hobby projects in Angular. This abbreviation was not easy to understand.

Had the text said: “Dependency Injection (DI)”, I would have accepted this line of text and moved on with my reading right away. Assume that people reading your documentation might be there to learn and understand. Keep abbreviations and niché terms away, or provide links or explanations to help those who do not understand, to get to a higher level of understanding.

Conclusion

Creating a readable and understandable text in your documentation is key to a good user experience. It can probably save you some support and meeting times which gives you more time and focus to develop.

Try to get feedback from the users, and whenever a question is asked that is or should be answered by the documentation, take a new look at your documentation and figure out if you can improve upon it to avoid that anyone needs to ask that specific questions again.

The next blog post on this topic will be about examples, tutorials and navigation in documentation, and how to improve those. Until then, good luck with your documentation.

About the author Magnus Skaalsveen is a consultant in Netlight Consulting. He enjoys working with front end development and user experience.