Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How do you learn new libraries without much documentation?

news.ycombinator.com

Post reply on HN
Print view View original

31–40 of 56 posts

Re: Ask HN: How do you learn new libraries without much documentation?

#31

Post by quanticle »

sillysaurusx wrote: post #28
quanticle wrote: post #22

Earlier quoted context omitted.

That's why you use a plugin that integrates ag or ripgrep into your editor so that you can see the context in your editor as you search.

Sure, that's fine. Personally, I hate dealing with vim plugin nonsense, and especially with getting vim environments working on a remote server inside tmux. But whatever works.

The other reason I don't favor this approach is that it totally ignores the fact that the organization of files and filenames also give you valuable semantic information. If I had a library, that, for some insane reason, decided to scramble its source across a gigabyte of filenames generated by a hash function, then I would definitely choose your approach. But most libraries (even horrible internal libraries) aren't like that. The name and location of files allows one to better understand whether the search result is relevant or not. As a cheap example, with `find` or `ag`, I can easily exclude the `test` folder, so that I don't have to deal with usages in unit tests when I'm trying to understand a piece of library code. But, if I'm modifying that code, being able to see unit test results is valuable, because it lets me know which test files I have to update.

With your approach, I get the full list of results, whether I want it or not.

Re: Ask HN: How do you learn new libraries without much documentation?

#32

Post by mytailorisrich »

loosescrews wrote: post #18

There is lots of good advice about how to figure out how it works in this thread. One piece of advice I have is write formal documentation of some form as you figure it out. Share it as widely as possible. If nothing else, it will be very useful for you and your co-workers in the future. It sounds like there is some sort of community you can share it with. Ideally there would be some way to contribute it back the to…

If you think that this knowledge will be important to your employer then try not to share it too much in an organised and documented way but rather help others on specific issues. This is more effective to establish yourself as the expert and go to person. If you write a comprehensive documentation they others need you less.

Re: Ask HN: How do you learn new libraries without much documentation?

#33

Post by jrumbut »

If you can't learn by example, which is the inductive process and the one that I am most comfortable with and it sounds like you are too, you need to learn by deduction.

For node or Ruby or other pure open source environments there are endless examples on the Internet and when you want to learn you can read 50 of them until they start making sense. When there isn't much documentation, you have to deduce the reasoning that went into the codebase or you may never make progress. It's a slower and more demanding process.

On a side note, before the explosion of web content, this was how a lot of programming had to be learned. Maybe talk to/bring in older programmers to help you?

Re: Ask HN: How do you learn new libraries without much documentation?

#34

Post by OmarShehata »

There's a lot of good advice in here about how to work around this situation but the best thing you can do here could just be: email this company and ask them.

If you are paying for this proprietary software, especially if you're still in the "evaluating whether we should spend a lot of money on this" phase, you should absolutely push back on them. Ask them all the questions you need, big or small. It's really on them to give you something well documented, and if they don't, they better be willing to answer all your questions about it.

I've seen this sort of customer behavior be the catalyst to get companies to actually document their stuff because all their engineers time was spent answering the same questions over and over.

Re: Ask HN: How do you learn new libraries without much documentation?

#35

Post by mercora »

thinkingemote wrote: post #5

Look at the library's tests. It's quicker and better for learning functionality than "just read the source code". If it's proprietary and closed and obfuscated then you need to familiarise yourself with reverse engineering toolsets.

maybe its just me and my avoidance of unit testing but often when i tried this it appeared overly complex at setting things up for testing and the code you need is buried in between some dozens tests and their setup. I think its a good idea to look at them but more often then not i did not want to get through this and just tried to understand the code flow by reading the source.

Re: Ask HN: How do you learn new libraries without much documentation?

#36

Post by mijoharas »

One thing I haven't seen people suggesting here yet is to use a repl!

Import the thing, and then look at what it provides. If something seems useful, try calling the function/instantiating the class, if it gives you an error message, try with different arguments.

Hopefully, you should have some idea of what the library is trying to do, so you should be able to see some functions that look like they accomplish the kinds of things you want. Guess what kinds of arguments they take and try it. If you can't figure that out, jump into the source and figure it out.

I find it's much nicer working interactively like this than just reading the source because you can immediately try things out rather than jumping back and forth all the time.

Also, some languages like python have a `help()` function that you can call with any class/method/function to get to the docs on it (I can't remember anything like that for javascript, so you might be out of luck there).

Re: Ask HN: How do you learn new libraries without much documentation?

#38

Post by EliRivers »

xadoc wrote: post #27

If the code has tests, I would start by looking at those tests. If it has no tests, then I would slowly try to build tests to document the functionality that I need. In your case being Angular that might be having simple html pages with the smallest module that you need. How to find things? If you're on Windows try AstroGrep http://astrogrep.sourceforge.net/ to quickly search and jump around in the code or in any sys…

Xadoc's advice above is good; unit tests. I work with poorly documented protocols that have been implemented "around the theme of the protocol" by hardware from a variety of suppliers, and this is how we work out its quirks.

A battery of unit tests, starting with the simplest functions it offers, and thence upwards into more complicated tests (i.e. chained calls of the presented functions) where we track what internal state we think the system should have at that point in the tests and interrogate it to discover what internal state it really does have.

Re: Ask HN: How do you learn new libraries without much documentation?

#39

Post by eru »

Not directly helpful for your case, but useful in general:

In strongly statically typed languages like Haskell, the types can often give you an adequate introduction into a new library.

There's quite a few open source Haskell libraries that basically only have type annotations, but no proper documentation. The latter would be better, but the former is already surprisingly useful on its own.

Post reply on HN