DEV Community: Gabriele Cimato

How do you manage writing technical articles ?

Gabriele Cimato — Fri, 03 Apr 2020 01:59:01 +0000

As I find myself scheduling more technical blog posts and practicing maintaining a regular writing habit I sometimes get lost in the details.

I believe that what works for me is writing articles that are a 10 minute read or less. When it comes to more technical stuff, the required time to complete the article, ensuring high quality content, increases.

This is sometimes a deterrent for me and I end up taking many days thus breaking the habit and not respecting the schedule.

Do you ever find yourself in a similar situation ?
Do you end up splitting your post in multiple parts to better manage your time and effort ?
What practice do you recommend ?

Build a leader habit: Bring the change you want to see

Gabriele Cimato — Thu, 12 Mar 2020 02:50:48 +0000

Have you ever hoped for a change in your job/company ? Have you ever felt the burning desire of leaving your job for a new one out of frustration ? Well...you're not alone.

It can happen to dislike how things run. Especially in a work environment. Unless you're one of the lucky ones. There are different ways we can react (or not react) to this feeling. I wouldn't say one is better than the other and as it often is with these things...it depends.

Look for the change externally

I went through a frustrating period at work. A period where things felt backwards. No organization, no decent planning, no coding standards, no peer reviews. This happened early in my career.

I tried to fix the problem seeking for an external change. I was trying to help hire someone who could enforce better practices. Someone who would push the team, and the company to follow higher standards.

And that's not a bad idea but you're tying your happiness to an external factor. This means you're depending on something you have little control over. You might get lucky but in an engineer mindset, you want to optimize for the worst case scenario. That being that you won't find that mentor, lead or whatever else that'll fix the problem. So how do you handle that ?

If you think there's not much you can do, it is worth considering leaving. And don't feel bad about it. Surrounding yourself with people that have higher standards is beneficial for your growth. This applies both on a personal level and on a career level. Is leaving the only solution ? No.

To some it might sound obvious but I had a "a-ha" moment. I did enjoy the people I worked with, I did love the project I worked on and the tech we used. Despite all of it, I thought about leaving, until my "a-ha" moment. What if I brought the changes I wanted instead of looking for them somewhere else ?

That's how I'll introduce you the alternative approach.

Be the change and lead the way

That was it! That was the best of both worlds. I got to stay, work on projects I love, work with people I enjoyed and bring the standards to a higher level. That's when I started pushing for changes, that's when I started taking the lead on projects.

My goal was to show a better, more robust way to apply good engineering practices to a project. The hope was for those practices to stick so that it would become the standard. That's when we introduced peer reviews, doc for best practices, and finally some testing!

I felt like that was one of my biggest contributions since I joined the team. My peer reviews were very detailed but not nit-picky. They often sparked some interesting conversations! ✨ ✨

My coworkers felt motivated to push themselves and do better. And on top of all this, my code got peer reviewed as well. This was absolutely incredible! I was learning from my teammates just from one simple decision. Being the one pushing the engineering team to do better paid off.

Conclusion

It's common to find ourselves being unhappy with how things run at work. We can take a few different paths and it's on us to understand which one is the best fitting. My recommendation is to always try your best to be the change. If you like the company, the people, the projects, that's an additional motivation to try your best first before moving on.

This is important because you want to make sure you did what you could to improve the situation. Unfortunately that doesn't always work. If you'll end up deciding to leave, you won't have any regrets.

But don't wait around for something to just happen! If you decide to go the external or internal path, make sure that is a decision that depends on you, not something else you have no control on.

Be in control.

Build a leader habit: Become the mentor you wish you had

Gabriele Cimato — Thu, 12 Mar 2020 02:46:05 +0000

Weather you got into tech by completing a CS degree, a boot-camp or simply self-taught, having a mentor to guide you through the first steps is always desirable.

This holds true at every stage of your career. In general we seek guidance to climb to that role or position we wish for. We hope to meet somebody who can help us avoid horrible mistakes. Someone who can show us good practices and get our thoughts in line with filed experts.

Sometimes we get lucky, sometimes we don't. No matter what your experience is (or was), you should aim to be THAT mentor.

The Mentor We Dream Of

Early in my career I was hungry to learn (and actually still am) and fill the gap with experts in the software engineering field. I was hoping to join a company with strong leads who could show me the way. I was ready to put in the work, I was just looking for some guidance.

I was lucky to have co-workers to learn from, but none were the mentor I was hoping for. I had a boss to report to, expectations to meet and the rest...I had to figure it out.

Most of the work an engineer is supposed to do, boils down to "figuring things out" yourself.

In my young and naive mind this is what I expected:

A senior who's an expert in the software engineering field
A patient mentor who could guide me and tolerate my mistakes
High expectations, so that I always have to try my best
Someone who is excited to share their knowledge and eager to see me grow
Someone who would gradually give me more responsibility
Someone who has clear in mind a growth path for me
Strict but understanding

I could go on even more but I hope you get the idea. I had high expectations and I was ready to deliver. But then reality hit. I had to learn the hard way. I had to find out what the best practices are, how to allow myself to make mistakes without disrupting anyone else's work, take great responsibilities early on, try my best to learn with books and any other mean available to me.

It was a real hassle but I learned a lot in the process. I was scared, upset, frustrated, fulfilled. All sorts of emotions. I made it our OK, without the mentor I dreamed of.

You Don't Need a Mentor

This is non entirely true. A better way to put it is "you don't necessarily need a mentor who's there holding your hand".

While I think that having a mentor is a privilege, you can still make it without one. There are many communities, resources, books, classes, workshops out there. It's hard not to improve unless you really don't want to.

You have to start by forgiving yourself for making mistakes. Try your best to make informed decisions but don't be hard on yourself if you do it wrong. Do you really believe that all those field experts out there had it right on their first try ?

It takes a lot of practice and a lot of mistakes to get better at anything.

My general recommendation is also the following:

Allow yourself to make mistakes in a contained environment so that your errors don't leak.

I find that making mistakes is one of the fastest way to learn. You tend to better remember that time you spent hours fixing a bug, but not really when everything went smoothly. This is why I reassure people around me (especially juniors) that making mistakes is OK. On the other hand we have to make sure that our errors are self-contained and don't leak.

Long story short, if you are willing to, you can set yourself up for success even without a mentor. It's a lot of work, a lot of active effort and a lot of mistakes but you can do it!

Learning in public can also be beneficial, once you put it out there you have the whole internet helping you out.

Be the Mentor

As I mentioned before I believe that having a mentor is a blessing. Just because you didn't have one doesn't mean that no one should. On the contrary, knowing the pain you had to go through why not become the mentor you wish you had ?

I always found that good mentor-ship is a natural trait of a good leader. A good mentor is also about empowering people around you. While I've been trying to go over main habits and traits of a leader one by one, you'll easily see that they are all intertwined.

This can be another way to empower people around you, help them grow, be patient, set the bar high but be understanding, show the way.

Conclusion

Early in our career we hope to be guided by an outstanding mentor. We won't all get this lucky and most of us will have to figure things out as they go.

That is OK and is not an impediment to your growth and your career. You just have to put in the work. If you want to be good leader though, you can (and should) become that mentor you hoped you had. Challenge yourself and others by teaching. Put your knowledge to test. Help others grow and guide them to avoid critical pitfalls.

BE THE MENTOR!

Build a leader habit: Empower people around you.

Gabriele Cimato — Mon, 02 Mar 2020 23:34:41 +0000

A good leader has an impact on the team they join.

They don't bring anyone down, they don't lower standard but they make the effort to show the way, possibly the better way. I've seen over and over again engineers clinging onto their knowledge convinced that's how they remain valuable to the team or the company. I have news for you, it only works short term, it harms your career development AND damages team dynamics.

Although we might feel better about ourselves being the "go-to" person for specific things within the office, we might risk to become the only person available for it, at all times. This means that you get stuck or pidgeon-holed into that role. This has two major drawbacks:

Eventually you might get tired of always being the go-to person for the same issues/tasks. It feels great in the beginning but it becomes tiring in the long run.
It can hamper your career development. If you're the only one able to solve a specific issue/task, why would the manager want to move you to a different team/role/project ?

How not to get stuck

There is a quite simple solution to this.

There's a theme you'll see across many of my posts. And it's the answer to a simple question which varies based on the context you apply it to.

What can YOU do to improve the current state of things ?

How can you change the situation without relying on external factors ? While some of you might be lucky enough to have a supporting team and a great manager, we are engineers at heart so we need to consider the WCS (Worst Case Scenario). Although we hear this mostly when it comes to solving algorithmic problems, it definitely applies to many real life situations.

Here are a few things you can do to "get unstuck":

1. Write incredibly good docs

I wrote about this in the past here, it definitely applies to the situation discussed as well. Some of the best engineers I had the pleasure to work with, were absolutely great at writing detailed-enough docs.

This means solid Readmes where all you had to do was follow a few steps. Explanations of the whys more than the what. Any team member should be able to be up and running by simply reading the docs and without any further need for communication. This liberates you from being the sole reference for a project and empowers other engineers to use or contribute to your work.

Writing docs is always a good idea, even just for your future self. So you have a dual benefit:

You empower your future self enabling them to pick up where you left off
You empower junior employees by showing them how things work passively (with docs).

Passive mentorship is a good starting point, but that's all it is. A starting point. So keep that in mind.

2. Automate what you can

Especially in 2020 I'm all for automation. There's so much out there to help you out, it's quite incredible. Even posting on my personal blog is now automated with a scheduler.

This can be quite useful for repetitive tasks. Instead of manually running a database query every 2 or 3 days a week to generate a report, automate it! Generate a report every day and save it somewhere where others can analyze it easily. On top of that, apply (1) again and document it all. With this you solve two problems at once: reports are automated so nobody needs to come ask, the automation is documented so other people can help fix any future issue.

You empower any other engineer by allowing them to pick up and possibly fix a task you bootstrapped.
You empower members of other teams by making sure they have the data they need at all times.

3. Teach and spread the knowledge

If you become the only source of truth for a specific piece of knowledge, you'll always be the point of reference. This ties well with my other post (Learn how to let go), where I suggest that a good leader knows when to let go.

That precious piece of knowledge can grow even more if you let other people nurture it.

Share what you learned. You are a lead so you don't need to be afraid that some specific information is what keeps you in that position. I have NEVER seen a leader lose their credibility or position by sharing most of their knowledge with their peers.

Empower people around you by showing them the ropes. Help them acquire some knowledge faster. It'll enable them to contribute sooner and become an integral part of the team.
Teach as much as you can about projects, company past failures or what you learned in the past/present.

I always found the last one extremely valuable. My goal has always been to elevate juniors as fast as I could by sharing everything I know about specific topics. My intent is to bring them up to speed so that we can have a 1:1 conversation about any technical topic.

I remember spending quite some time explaining how state management works in React in great depth. Then showing the good and bad of Redux and how to use it effectively. Within a few weeks I was able to discuss with other junior devs how we should go about handling a complex feature, letting now them tell me how they would do it. This was only possible because I filled the gap in their knowledge by sharing and teaching them what I knew.

Conclusion

There is no reason why you, as a lead, should keep your knowledge secret. We've seen how beneficial sharing and empowering team members can be. From a more self-centered perspective, it unlocks your growth. From a self-less perspective you allow the team to grow. That sounds absolutely great on all levels!

Be the type of leader who brings the best out of people. Their growth is your growth!

👋 Hi, I’m Gabri! I love innovation and lead R&D at Hutch. I also love React, Javascript and Machine Learning (among a million other things). You can follow me on twitter @gabrielecimato and on GitHub @Gabri3l. Leave a comment if you have any questions, or send a DM on Twitter to say hi!

A surprisingly good interview

Gabriele Cimato — Mon, 17 Feb 2020 17:57:43 +0000

Interviewing for a software engineer is hard. Not only for interviewees but for interviewers as well. The whole process is a 2-way interaction:

The candidate is supposed to demonstrate technical capabilities and inter-personal skills
The interviewer should provide insights about the company and the day to day work

Although this is a simplified point of view it still holds true. Leaving a bad impression on the candidate might make them skeptical about the company. Unfortunately that is not always taken into account from interviewers. I've been in all sorts of positions and had many different experiences. This time around I want to present a few surprisingly good ones as the interviewer!

There are two instances that I remember very well. One happened a few years ago when we would provide candidates with a small project. They could take up to a week to send it back, it generally took 1 or 2 hours to finish.

I remember creating this mini project with one thing in mind: make it relevant to the actual day to day work!

If you assign a take-home project, make it relevant to the position and the company

It was a challenging enough sub-task of a bigger project that would also give the candidate the chance to shine. What I was expecting was NOT a fully functioning, all features covered and tested type of project. Just a simulation of being assigned a task, working on it and submitting a PR.

Some people were all over the place. They did not follow coherent patterns or straight up missed major features. Sometimes they would just use many different approaches to do the same thing.

The attention to details

This one candidate had everything well organized, even the commit messages in her repo! It was a breath of fresh air. The project was completely finished and styled. Everything about her code was in the right place, following organized patterns. Needless to say she was brought in for an onsite and was hired quickly after!

What impressed me was not only the task completion, but the attention to details. It really felt like she kept in mind her future self and coworkers as well. Following specific patterns helped understanding where to find anything very quickly 🎉

Showing off your attention to details can make the difference

The discouraged

In another occasion we were interviewing for a Unity developer position. This time around we did not have a take-home ready. As you can image we went for the always-dreaded coding exercise 😦 .

She was a junior and a bit nervous, as soon as I mentioned the coding exercise I saw the horror look in her eyes. She was very upfront and said: "I'm sorry I'm not very good at this type of things".

I do my best to make sure the person on the other side of the table understands their whole career will not be judged by one coding exercise. I always mention a few things:

It doesn't matter if you solve it perfectly
Time complexity does not matter
We just want you to do a little coding
We just want you to tell us how you approach it
Ask as many questions as you want! We're here to help you!
This is not Google!

She was still very skeptical and while I was trying my best to make her feel comfortable, I was starting to be skeptical as well. She then started getting into what a solution could be, coded something simple but effective. Sometimes she would take longer pauses and I had to ask her questions. At some point she was very discouraged.

That's when I changed approach a bit and was proactively cheering for her. Letting her take a minute and convincing her that she could do it with almost no help. It worked like magic! She went through with it and got to a solution she thought was just OK.

Little did she know that it was actually the optimal solution! She just needed a little push and a bit more confidence. We ended up offering her the position and she sadly had to turn it down, some life changes required her to move to a different city unfortunately.

At times you need to encourage and support the interviewee. Some don't perform well under pressure but you should try your best to make sure it doesn't disqualify them!

Conclusion

I have many more examples of good and bad experiences but these two were the ones where I learned the most. On one side the attention to detail from a candidate really put her ahead of anyone else. Showing off how much you care about quality and coherence is never an issue! On the other side we need to keep in mind that interviewing is hard. Sometimes after we haven't interviewed for a long time we tend to forget how stressful it can be. As an interviewer always remember that you should try your best to make the interviewee comfortable. Encourage them, sometimes even with a little help!

Have you ever had a great interview experience before ? Share with us in the comments!

CSS power-up: count code lines in pure CSS

Gabriele Cimato — Wed, 20 Mar 2019 06:19:23 +0000

I decided to start a series called CSS power-up! I will be collecting small posts about neat CSS features. There's one specifically that I was very impressed by. Not only for how intuitive it is but also for its widespread browser support.

Tired of having overly priced note-taking apps, or free ones that don't offer what I need, I decided to create my own! That's why I started a side project that led to rediscovering an interesting CSS property.

It all started with Slate.js, which provides a library to build rich text editors. One feature I was looking for in my app, was the ability to add code blocks. I soon found a plugin called slate-code that does it for me. How convenient! After fiddling with it a bit here's the result:

Now this looks fine but, I'm sure you noticed something is missing. Where is the line count ? Armed with patience I decided to go down the rabbit hole, convinced it would be a painful journey. At first I thought about using some sort of index reference to each line and display that on the side. But handling deleting and insertion of lines seemed overly complicated 🤔.

Then I remembered that you could do that very intuitively with CSS only! I was thrilled 😀! The way it works is by creating a named counter and specifying which CSS class increments that counter. On top of that you also have access to the counter value that you can display as content.

Let's dig into it. First let's define the class of the container of the code block.



.code {
    background: #f7f9fa;
    border: 1px solid #e6e8eb;
    font-family: "Lucida Console",Monaco,monospace;
    overflow: auto;
    padding: 8px;
    white-space: pre;
    counter-reset: line;
}

With counter-reset: line we are defining and initializing a counter named line with the value 0.

Now we need to determine which class will be in charge of incrementing the counter. We use the counter-increment property for that and give it the value of the counter name we want to increment, in our case line.

To finish up we also want to display the counter value. Using counter(line) with the content property that's exactly what we get. As an extra you can add the -webkit-user-select: none to prevent user from selecting the counter values. This is helpful when you want to copy a whole code block.



.code-line::before {
    counter-increment: line;
    content: counter(line);
    -webkit-user-select: none;
    font-size: 10px;
    color: grey;
    margin-right: 10px;
    text-align: right;
    display: inline-block;
    width: 18px;
}

And the result is the following:

The rest of the styling is pretty arbitrary and up to you. As you can see it was quite easy to add something as simple as a line count. You can find the full reference here. At first I was very thrilled by the simplicity of this method then I remembered that I had to check browser support.

🎉 What a victory! We went from panicking about ways to implement a line counter to having a simple CSS property that is widely supported. I hope you found this as interesting as I did. Is there any not-so-popular CSS property that left you "wowed" ? Have you used the line counter before ?

If you want to see a live demo, you can find one here.

Build a leader habit: learn how to let go

Gabriele Cimato — Wed, 06 Mar 2019 14:30:48 +0000

I would like for this post to be addressed to everyone, junior to senior. I believe it will resonate more with senior engineers though. Nonetheless I invite everyone to give it a read!

You can find countless self help books talking about "getting rid of the clutter", "focusing on things that matter" and "keeping things minimal". What you'll read goes in hand with many of these topics. I wanted to go more into specifics, especially for engineers in leading roles. I will split the article into small sections so you know exactly what to let go of. I also touch on other aspects of being a good leader so get ready to take notes!

Projects you started

...that will be passed on to someone else

This applies especially when you join a startup at early stages. You start developing anything, from an internal tool to the backbone of a production app. You get your hands dirty, the team is small and you have to hack it together. But you're proud of what you build, like every engineer. What you thought was a small "internal admin tool" becomes a behemoth. A do-it-all dashboard that holds together all internal data. As the company grows the internal tool grows, up to the point where you can't maintain it alone. At this point a few great opportunities will present themselves:

Mentoring
Building Trust
Letting go

First of all you have the chance to show what you built to a junior. You can mentor them so they can learn their way around the code base. You can teach them about the mistakes you made along the way. It'll help them not having to learn the hard way (mind you, they will learn plenty the hard way so, no need to add more). Then, once they are comfortable, they start adding/removing features, fixing bugs and taking ownership little by little. You can now let go.

Do not obsess over the project because you built it. Do not obsess over the project because you want control. Do not obsess over the project because you want things done "your way". Do not obsess because you want to feel needed. Let go. Let go and trust the coworkers you mentored to take over, they will do just fine. And what if they are completely lost? They can come to you and ask. That easy.

You already gave it your best, you put plenty energy in it. It is time for you to move on and focus on whatever you can bring next to the company. Especially as it grows there will be a ton of new projects, new tools, new apps. Or there can be old projects, old tools, old apps that need help! But remember that clinging onto a project you worked on is not healthy:

You will always feel like you need to be involved
You will always feel like you need to keep an eye on it
You will always feel like you need to be in every meeting about it
You will take away focus and energy from things you need to work on next
You will split yourself too thin and burn out

Learning to let go is a beautiful thing. It allows you to focus on what matters. You will avoid wasting mental energy. You will avoid keeping control on things that do not need you. It's not easy, because we all love to be involved. It's not easy because we will feel "cut out". But once you let go, you feel lighter. You don't have to worry about it anymore. You can focus on what's next and avoid unnecessary distractions.

If I didn't learn how to let go, after many years within the company, I would need to be part of way too many meetings. Way too many code reviews. Way too many architectural decisions. At some point you need to trust your team and focus on what you do best.

Projects you started

...that will become obsolete

Writing code is an ephemeral art. Software becomes obsolete and so does the code you write. Do not get too attached to that beautiful folder structure, script, util or anything about the project. Be proud of it, learn from it but don't get attached.

Especially in fast paced environments projects born and die quite often. It would be an emotional roller-coaster if we always got attached to what we develop. Learn to let go of it, put in your backpack and move on. Even though such projects might end in the trash bin, keep with you the lessons you learned while working on it. Those are invaluable and will bring you closer to be the amazing engineer you're meant to be! For this reason here's a hot tip:

When you work on a new project, no matter how small it is, try to add or use something new (even as little as a small utils library). Put yourself in a situation where you can be productive. But also give yourself a chance to learn something in the process.

I have even been in scenarios where I built a small interface or a little dashboard. Then, after a week, it became completely useless. That's because we learned things about the problem that made it not necessary. Poor planning ? Maybe, but sometimes that's part of the game. Was it a waste of time ? No, because I made sure to use a different UI library, so I was able to learn something in the process 💪

Your ego

This is a tough one. To be honest they all are. They seem easy on paper but it's difficult to adjust your mindset to it. A good leader, heck, a great leader does not seek credit. A great leader does not say "I", she says "We".

A good leader is an established presence within the company. For this reason you need to understand the role your ego plays in a work environment. If you don't keep it in check, you risk to put other talented or growing engineers in the shadow. Learn how to use positive reinforcement and let others take credit and shine when the time is right!

Sometimes it's hard because we all love praise. This is why putting your ego on the side for the greater good is hard. Be the kind of leader who helps engineers to grow with suggestions on implementations, but deal with this quietly and privately.

Be ready to forgo credit for suggested improvements

This is something extremely valuable that I learned twice: on the job and from F.P.Brooks on "The Mythical Man-Month". If you gave the suggestion that helped someone better an implementation, be a good leader, let go of the credit.

I would also like to give you a few examples of what a good leader should NOT do:

When a junior coworker is asked to present a new technology to the team as an opportunity to shine, don't shoot them down while they are presenting. Don't interrupt them with questions, and if you really need to do that (just don't) make sure you know the answer. Talk to them privately if you need to correct them.
Do not take it personally when someone reviews or critics your work. Understand what you can take from it and move forward (this tweet from Sarah is a good example).
Do not demand to always be the one to work on the "cool" company projects.
Do not try to keep every technological aspect of the company under your personal scrutiny, delegate... let go!

There's many more that I unfortunately witnessed. I hope these will give you a few hints on what to expect from a good leader, and how to be one! To be honest this is just a small part of it. Learning how to let go is a main ingredient that has a subtle but significant effect on many scenarios. The risk is that your ego can get in your way. This will prevent you from making decisions clearly and fairly. My suggestion? Let it go (cit. Frozen).

It's a way of thinking and behaving that's beneficial on so many levels, it allows you to declutter your brain. You have to keep fewer things in mind because you are now delegating more. You will take pride because you helped other engineers grow within the company. By doing so you let them become the people you can trust and delegate to!

It's really a win-win 🎉!

How to make your future self happy by writing good docs

Gabriele Cimato — Wed, 20 Feb 2019 06:15:00 +0000

This is a little overview of common problems faced when working on a new or old project. Sometimes making a little effort up front can save you time and energy down the line. Writing good docs is like getting ready for your future self to high-five you ✋! We’ll see a silly example and a few recommended practices to get started with a good README.md.

The Struggle

I’m almost certain that in your career, or in your everyday life, you faced a situation before that makes you think:

“This problem looks familiar, I’m pretty sure I solved it before. If only I could remember how I did it!”

Especially coming from an engineering perspective this happens quite a lot. Repeated patterns, functions or bugs we’ve met before that require us to go through the exact same past effort to overcome an issue. Sometimes we are willing to do it again, so we go ahead and figure it out once more. Some other times though…

An example

I lead the R&D department at Hutch and we often have to dig deep into new and unseen technologies, frameworks or languages. You try and experiment a lot and can’t expect to remember everything you interact with. You work on something for a couple months then, once you’re done, switch to something very different. Or maybe you just work on the next step in a pipeline.

Then, when you least expect it, it happens. You have to go back to that framework you used 3 months before to make a change. You give it a look, a puzzled one 🤔.

“Oh, actually I remember this. To make it behave this other way I go here…change this…and voilà!”

At that moment you feel pretty good about it. You were able to recollect how things worked. You’re even proud of yourself for leaving simple docs on many of the functions you wrote many moons before. Then with a light touch of your mouse, you run the project and…

⛔ ERROR! The main frame has some cowbells directed towards Mars, this is not allowed.

😵 Yikes! This looks very cryptic. You take a look at the code you changed and, well…you try to run it again. Maybe something will automatically change. Maybe looking at it again had some quantum effect of some sort. Nope.

⛔ ERROR! The main frame has some cowbells directed towards Mars, this is not allowed.

You then read through the comments or the docs. Nothing mentions this error, nothing points you in the right direction. This error is so distinctive that you’re sure you saw it before, and also solved it before. As daunting as it feels, you have to figure it out…again!

You start googling the problem and notice some previously visited links.

“Great! This link is probably the one that helped me with the error…phew. Crisis averted!”

You then scroll the page and, oh no! More…many more visited links. So now you have no idea which one led to a solution if any. And so the search continues until eventually, you figure it out — minutes, hours or even days later.

Good documentation covers more than just happy paths 🙂

I learned this the hard way. Multiple times. It’s often easy, although admirable, to add docs to your functions/methods/classes with the assumption that everything will work well.

I always try to make life easier for whoever will dig into my code. That includes future me! So I diligently add docs to almost all of my functions but the trivial ones. As many have said for decades:

Your comments should explain the why more than the what.

Your code should be “self-documenting” so that any added comment addressing the “what” would result redundant.

In all fairness, I tend to add comments even for the “what”, only when I know a function is either long or somehow intricate. Adding a few lines of comments would allow me to skip examining every line of code. This has been helpful countless times and I absolutely recommend it!

But documentation is not just lines of comments on a function. Good documentation is a well written README.md. In some scenarios even a full-fledged dedicated website for bigger projects (see React, Redux, Vue, Slate, …).

The projects mentioned are all open source. Teams are basically compelled to go in greater detail to help people start using their framework or library (and have been doing a great job in that regard!). But what about smaller private projects? What about those projects that will only live within the company (no matter what the size of the team is)? And what about all those issues that are not purely code related?

More often than not we tend to skip the README.md file or dismiss it with a few lines only. I’ve been following a simple yet powerful practice to make this task less intimidating and help go beyond the happy paths.

A basic approach to creating a good README

When mentioning “happy paths” I refer to the practice of assuming everything will run smoothly. This means we are only addressing each step of a process as if it will always succeed.

Unfortunately, that is not always the case so, how can we make our lives better? How do we make sure that even the not-so-happy paths are covered?

Here are a few suggestions:

Start by writing down a few lines about what the project is about and what problem you are trying to solve**. This helps you, and whoever goes through it, understanding the intent of the project.
As you go about setting everything up, make sure you add each step to the README.md. It doesn’t have to be well formatted and phrased, it just needs to be there for now. This usually comes in the form of installation instructions.
If at any time you face an error of any sort, add a section at the bottom. You can call it Common Errors. There you add some details about the error you faced and how you solved it. One crucial thing I like to do here is add links to the source of the solution (or anything that helped me get there).
When I reach a stable point in the project I try to install it on a new machine (if it’s a possibility). The goal here is to ensure that the set-up steps we listed before are correct and work as expected.
Most importantly, you need to have a section answering the question: how do I use/run this project? This should be as clear as possible, so put some effort into it! Sometimes, though, you can’t answer this question until later on. You can wait until you are in a working/running state to update the README.md.
Put aside some time to review and clean up your README.md file. Most of the time you’ll probably need to update it.

This is often enough for small size projects. For mid to large-sized ones it can be a starting point to develop some good practices. Talk about it with the rest of the team and agree on a common approach that will make everyone happy. Keep in mind that maintaining the docs up to date is crucial! Hold each other accountable for it and after the initial effort, it’ll become natural, just like a simple refactoring!

Conclusion

Writing good docs involves maintaining a good README.md and documenting the whys in your code more than the what.

If you make a small effort and incrementally build up a good README.md it will feel less intimidating. Not only will it make your life better in the future, but it will help anyone else contributing.

Don’t cover only the happy paths expecting everything will work, also cover eventual errors that you face or any issue a newcomer might face. Keep a dedicated section for this.

Bonus: when estimating your work with a PM, take into account the effort required to write/update the docs. Don’t underestimate the fact that good docs require a good amount of time. But that time is very well spent!