DEV Community

Oguzhan Yagci
Oguzhan Yagci

Posted on

How to read a documentation?

My biggest issue so far as a software developer is reading a doc. How many times did I open the docs of a new tool I am learning only to end up on Google asking how to do this and that.

Man pages are a bit easier to understand because usually I use them on specific functions. But for a frameworks like ExpressJS or bigger ones like Qt I am completely lost.

What are your tips to read a documentation efficiently?

Top comments (3)

Collapse
 
aurelkurtula profile image
aurel kurtula

I read them after the fact!

I plan what I need to do, I google all that I need and I get the code running.

Then I get into analytical/writing mode.

Whilst writing the code, I make extensive use of branches. For example, learning ExpressJS for the first time, the hello world gets a branch "step1".

After I get everything done. Or after I'm deep enough. I get back to the first branch and start picking the docs apart.

app.get('/', (req, res) => {
  res.send('hello world')
})

Even for this I use google: "expressjs get" will take me to do right section of the docs right? Once there I'm more confidant, I know that I already coded everything, now I just need to understand what it all means.

The docs say "Returns the value of name app setting, where name is one of the strings in the app". That wouldn't make sense if what you wanted is to send "hello world" to the browser, but now that you already got that, you are free to find it interesting.

Ok I don't really care about app.get('title'); but interesting. Now I see a link to "Path examples", clicking it, aha, that's what I needed, holy, I can set an array. Wait, the example uses array in the use method, let me try to change the hello world to an array:

app.get(['/', '/hello'], (req, res) => {
  res.send('hello world')
})

Haha, it works!

(Honestly, this is not scripted, I genuinely didn't know we can use arrays in there)

Basically I found that reading the docs to learn the basics doesn't work for me (I have a feeling it will work after I ready lots of docs over the years) so for now I'll use them as wikipedias rather than tutorials.

Hope this gives you some ideas.

Collapse
 
ironicnet profile image
Ezequiel Calderara

Mmm usually this is my approach:

  1. Go to the site and read the getting started, to have an idea of requirements and setup.
  2. Try to really understand what the framework or library does.
  3. Try to do the same setup or have the same requirements.
  4. Look through the tutorials until I find something similar that I want to achieve. I Try that.
  5. If it worked, I try to understand why it worked.
  6. Worked or not, I google for alternatives way of doing that. Or pros and cons.
  7. If google has results with some example, I try that. Back to 5.
  8. If it doesn't work and google doesn't give me good results. I try to read the API of the framework or library to see how it can be achieved.

If what you are looking for is because of an error happening:

  1. Read consciously the error message. Usually it says exactly what's happening.
  2. Try to look at the FAQ or Troubleshoot page.
  3. Check versions, requirements and configurations.
  4. Google the exception message.
  5. Google the first line of the stack trace, where it says which component is failing.
  6. Look up for the source code. Search for issues on it.
  7. If you can reproduce it in a small test, submit issue or try to fix it.
  8. Meanwhile, look for an alternative library or framework
Collapse
 
aswathm78 profile image
Aswath KNM

My approach will be videos first.

I will watch people do something with that library/function/framework

Then I will watch more videos and familirize myself about that topic .

Since I know what it can do . Now I will try to implement something of my own

Definitely I would've done something wrong . Mostly syntax errors.

Now I copy/paste errors in Google . It'll show me a bunch of answers . Now I will understand what I've done wrong .

Now I would've implemented the same thing , what they showed I'm the video

Now I search more about the library/ framework/function understand more about what it can do.

Now I will have a partial idea about library/ framework/function.

Now only I would've started reading documentation.

The trick is to familirize first . Once we try to understand the term in documentation , we can simply read it .

Better get a mentor .