New year, new project. Joining an existing project is hard. There are no shortcuts. But there are ways that the existing team can use to ease you in. The sooner you are set, the sooner you become productive which is good for everyone. In today’s post, I will tell you about an experience I once had dealing with optional steps in a document. Let’s jump right into it!
Who wants to do unnecessary work when not doing it gets you the same result? I actually remember that one time where I skipped the only optional step in a doc to set up my machine for development. I got stuck for about half a day, debugging, asking around, etc. Turns out the solution was to execute that one optional step I skipped earlier.
Optional instructions should be just that, optional. Skipping optional steps should not become a big deal that gets you stuck down the line. And yes some people will follow guides to the letter even the optional stuff. But this not the case for everyone. I personally prefer making the least effort and work as little as possible to reach a goal. While I would prefer to not have optional instructions altogether, I happen to put them in my documents if their implementation/avoidance has no side-effect on the document purpose. Suggesting to use a command line to clone a repository instead of your GUI tool of choice is a fair example of that.
Obviously, the key here is not to just complain. The point here is to create some awareness of how certain behaviors can cause more pain than good. I want to help documentation writers to avoid these by getting in the shoes of someone who knows nothing about whatever tools they need to use. Users can often be complicit in documentation issues as they might run into issues and not update the documentation to reflect them or remove the parts that cause said issues. I hope that people that write documents make them more practical. Also, I wish a world where documentation users will at least report issues they encounter on a sometimes outdated piece. Even better, a world where users will fix the documentation when they have editing powers.
In that particular situation, I reviewed the document and realized that it was aimed at different audiences, with different aims. On one hand, the new maintainers/developers and users of the framework on the other end. From there, I decided to write a new developer starter pack documentation and ran through it several times. No more optional steps this time.
By running through I don’t just mean reading it over and over. Doing it that way might cause the same issue as the existing document. Indeed, if you already set everything up, it’s always going to work even if you forget a step. Therefore, I scrapped the whole setup of my machine over and over. Thus, repeating all the steps of the newly written documents every single time. Then I followed the same process to rid the existing document by removing the developers’ related stuff and keeping the user-friendly bits for consumers.
Once I was satisfied with the changes, I ran them through the team that approved them. Now the future devs that will join this team can enjoy a slightly less confusing doc with no optional steps which was my original goal. The added bonus is that the other teams that consume our APIs and libraries have a cleaner documentation without the stuff they don’t need and get to their local integration setup faster. The key to a good guide is to make sure you put yourself in the shoes of its consumers. Not just in your head but by practicing your preach.
