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

41–50 of 56 posts

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

#41

Post by cameronbrown »

- Ping people directly in that community.

- Get yourself a notebook (or Google doc, whatever) and thoroughly write down everything you learn.

- Walk through the source code methodically, and read the jsdoc/function names wherever possible. Don't read too much into implementation.

- Use whatever tools your comfortable for this. Generating call graphs or reading through tests first make a lot more sense than trying to read the entire library.

- Start by documenting Hello World and go from there.

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

#43

Post by jyriand »

Usually I just look into source code. Use 'tree' command to see the folder structure and then pick a file that seems relevant. Then I go to the bottom of the file and work my way up (usually the main entry points are the bottom, depending on the language of course).

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

#44

Post by mbzi »

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…

This is good advice. I would also extend this and write out an FAQ / stackexchange for the next engineer at your company who has to go through the same learning curve.

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

#45

Post by TimD1 »

mytailorisrich wrote: post #32
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.

Yikes. Would you want to work in an environment where all your coworkers acted like this? Your suggestion may be necessary in a cut-throat workplace, but I'd be more inclined to GTFO and work somewhere that my team members actually try to help each other, instead of always acting in their own self interest.

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

#46

Post by mytailorisrich »

TimD1 wrote: post #45
mytailorisrich wrote: post #32

Earlier quoted context omitted.

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.

Yikes. Would you want to work in an environment where all your coworkers acted like this? Your suggestion may be necessary in a cut-throat workplace, but I'd be more inclined to GTFO and work somewhere that my team members actually try to help each other, instead of always acting in their own self interest.

Did I suggest not to help? No, on the contrary.

Of course you should be helpful, but you should also be smart. You want to be seen as valuable AND as difficult to replace. Help your employer succeed and help yourself succeed at the same time.

What would you rather hear in management meetings?

"We can't let Bob go, he's the expert on X, everyone goes to him for help and we need him" or "Sure Bob is an expert on X, but he wrote down all he knew so we'll manage".

See, it's not about not helping, it's about helping while building and retaining leverage.

That's why companies want to encourage "knowledge sharing". It's not to foster a friendly atmosphere, it's to be robust against someone leaving and to prevent someone from having too much leverage. Most experienced engineers know that and tend to be wary when asked to document what they know in details and/or to train others.

As to act in one's own self interest, well sorry to be the one to break it to you, but that's how the world works in general and that is especially how the workplace works. And in fact that's how everyone works when there's a choice to be made. The sooner you realise that the better off you will be.

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

#47

Post by angrygoat »

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 last point is really important. The missing documentation is clearly impacting your productivity: you absolutely should raise this as in issue with more senior devs or management. There are a number of ways to respond, and they should be pleased that you have flagged the issue early.

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

#48

Post by akho »

sillysaurusx wrote: post #17
izacus wrote: post #14

Earlier quoted context omitted.

This sounds like trying to create a poor man's IDE with go to definition / find usages functionality. Is there an IntelliJ product for JS yet?

I regularly read and understand 50,000+ line codebases with this technique. Again, I suggest trying it before dismissing the idea. A good IDE is nice, when they work, but this fallback has worked 100% of the time. CLion is for C++. PyCharm is for Python. Webstorm is for JS. But Vim is for everything. To put it differently: how often do you use ripgrep on a large codebase? If the answer is "often," then every time you…

Why would you switch to the terminal to use grep from Vim? :grep works perfectly well, and is more convenient than search in a flat file (better context for matches, quickfix list instead of n/N nonsense).

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

#49

Post by mytailorisrich »

EliRivers wrote: post #38
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 interna…

These are exploratory tests rather than unit tests, but your point stands.

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

#50

Post by PowerfulWizard »

This is what my priorities would be:

1. Make sure you have a good debugger set up for any existing code. This is to answer the question of exactly how a function behaves, what are the meaning of parameters, etc. You know you're going to be dealing with undocumented functionality, so you need a way to quickly answer your own questions.

2. Someone at your organization is paying for this right? Ask them to pressure the supplier for one-on-one support to answer your questions regarding how to use it. You want someone on a video conference who knows what they're talking about so you're can explain things quickly and not have to write up detailed emails and wait for response.

3. You could try to document it yourself: Locate all the exports and create a list of them. Browse it for key names and concepts. Write down the purpose of each, and their relationships. There might be a lot of these items but it won't be infinite. Even if there are 500, if you do 20 a day you'll be done in 6 weeks and by that time you should have a pretty good picture of what's going on.

Post reply on HN