Translating Documentation : An Introduction

During the course of my software engineering intensive, instructors and coaches often talked about the “journey” of learning a new thing.

Achievements are never a straight line, but it’s easy to gloss over the curves along the way

This journey has twists and turns, and you can get stuck in the weeds (or “swamp of despair”), but a key takeaway is that you don’t have to go it alone. By connecting to your community, and embracing positive persistence, you can get from the dread of “This is going to be a lot of work” to the solid “[This is] ok but it still sucks,” ideally skipping over the depths of the dark swamp.

One way that developers can work together is through documentation. Documentation is simply the instructions and insight into how a language/framework/method/etc works, as written by folks who built the thing. Documentation is a means to share with other developers who have not used the corresponding language/framework/method/etc before, to ease the approach on the on-ramp to understanding.

Unfortunately, not every developer has leveled up their communication skills in tandem with their coding skills, and there is no one way to write documentation. I can recognize the challenge to standardization of documentation, because of the wide range in audience. Take for example, two developers. Developer A has already written in a few languages, but is brand new to Ruby. Developer B is entirely new to programming, and is starting with Ruby. The questions these two developers may have, and the language these developers have to express their questions and understanding can vary greatly, and without practice, it can be challenging to find meaningful language that speaks to both, without talking down to either.

Thankfully, documentation is also a great resource for examples of code, which helps demonstrate what should happen, in case the text description does not give the reader the “a-ha!” moment. Whether the shared language between the reader and documentation is the written description, or the code itself, the reader can gain understanding of the topic, as well as new tools to describe their code .

When I first started learning Ruby, I found myself reading through the documentation, entirely mystified, lost, or confused. When I look back at that same documentation, I’m on the other side of the emotional journey arc, and have a better appreciation of what it means to not feel that confusion. Progress!

Under the text “Definitely Lost”, a stork not knowing which way is up on the map, or me, as a baby Rubyist

I’d like to take the opportunity over the next few posts to break down some pieces of documentation, in order to lend a helping hand to future new developers. I will update this post with links to the “documentation translations” as I write them, and am happy to tackle parts of documentation by recommendation as well.

• Translating Documentation : Reading Between the Lines

Before concluding this introduction, I’d like to address one more thread woven into the topic of documentation — the ever-pervasive “Just read the docs!!!!” response, especially in terms of asking for help. Documentation, as I described before, is an on-ramp from confusion to understanding for folks who are unfamiliar with the documented topic. This is a wonderful thing! Using the documentation as a gate-keeping bridge troll is decidedly NOT.

As we are reading documentation, there are a few things to remember:

• It is entirely possible that it was written from a perspective of already knowing certain things. If you don’t already know those things, it can be more challenging to understand.
• It is also entirely possible that it was written with beginners in mind, but that the explanations still don’t make sense.
• Not knowing something only means that you don’t already know it. It is not a judgement on any facet of your being, full stop.
• Learning something new can feel uncomfortable, because it’s different. This discomfort is ok! You are actively re-calibrating the Things You Understand to include Something New.
• As you are learning this new thing, ask yourself questions, just as you would someone else — this will help you get a better grasp on things you do understand, and better pinpoint things you don’t understand.
• After the personal reflective questions, reach out to others — either to share what you’ve learned, or to dig further and focus in on what you don’t understand.
• The documentation covers a wide range of scenarios and use cases, but may not specifically answer the question you have. If that’s the case, take your query to Google/Stack Overflow/fellow developers/the creators behind the project you’re using — as appropriate, especially for the last piece. Again : you’re not alone in the internet, and you don’t have to go it alone to gain understanding!