Read the docs

Reading the docs is so important. It is so easy, when you are confronted with a task, to just jump in and start doing. It feels right. It feels natural. It feels like progress.

The problem is that it may be motion, but it probably is not progress. You may be spinning in circles rather than moving towards your goals.

So, the solution is to read the docs. Documents are key ways of transmitting knowledge and will let you reduce effort or reuse solutions. There are a couple of different kinds of documents that are worth reading:

Requirements/high level project docs: These are typically written specifically for the project, and will help give you a sense of direction. It will help you find how the work you are doing fits in. Depending on the size and maturity of your organization, you may find these documents in various levels of detail and completion.

If you don’t find any at all, take the time to write one, even if it is just a one page overview that answers “what are we trying to accomplish”. Send this to a senior member of your team (or of the business, if there aren’t senior technical team members) and ask “hey, did I document what we are trying to accomplish here?” If not, revise until everyone is on the same page.

Writing down these requirements can save tons of time, as they can bring new members of the team up to speed as well as bring the current team into alignment. If you are working on a project with human interaction, clickable prototypes can also be useful in determining the functioning of what the team is building.

Try to keep these documents up to date, though that is always a struggle. Whenever I start a new project, these type of docs are the first thing I look for, and if they don’t exist, I start writing them. They can take many forms and can include things such as overarching goals and terms (especially if they are not common vernacular).

Even a paragraph in Slack pinned to the channel is better than nothing, but I typically like to put them in a google doc (if the keeper of the doc is non technical) or a readme in git (if the keeper of the doc is technical). Having these kind of docs available will keep you from heading down errant pathways that aren’t moving toward the end goal. It reduces your effort.

Platform and library documents: These are user manuals for the tools you are going to use. Oftentimes they’ll be provided by an outside source (an open source project or a company) and are general in nature. As a new developer, hopefully you’ll have some internal guidance on these tools (even if it is just a conversation on why language X was chosen). But no matter how you arrive at the platform/library/framework, it’s a good idea to learn as much as you can about the tools you are going to be using. I tend to bounce back and forth between experimentation and documentation, but please find the learning style that works for you.

A thorough read of the docs will save you time. Recently I was using a snap in CMS for Ruby on Rails, a web framework. I wanted to customize the back end system and jumped immediately into prototyping code. Later I was reading through the docs and saw that there was official support for my customization. I burned a few hours of time figuring out the wrong way to do what I accomplished, then had to spend more time doing it the right way.

One of the difficulties of reading these kind of docs is sometimes you don’t know what you need to know, nor how to look for it. I can think of a few times where I was working in AWS. I scanned the documentation and got to work. Later, running into an issue, I went back and re-read the documentation. Lo and behold the solution to my issue was in the documentation, I just didn’t know enough to know that I needed that knowledge. There’s no way to avoid this. But having scanned the documentation for the tools you are using to solve your problem make you aware of any pre-built snap in solutions, and also may point out extension points that you’ll want to be aware of as you build out your solution. Reusing code and concepts will save you time and/or money.

However, don’t spend too much time reading docs and thinking about the problem(s) you face. I’m often confronted with a problem that is newish, whether in a domain that I’m unfamiliar with or combining two or more existing pieces of software in a novel way. Sometimes there’s no way forward but to just start thinking and coding, and documentation is no guide.

Knowing the bounds of the problem and information about the tools you have to solve it will help you determine when you are in a new space, and when and where you’re on well trodden ground.

This was initially published here: https://letterstoanewdeveloper.com/2019/04/15/read-the-documentation/