I think "reading the manual" can be be interpreted not just in the literal sense of whether there's an actual manual, but also in the metaphorical sense, to make sure we're considering easily available sources of information. Great advice.

Yep this is a really important skillset.

I've written a post around this topic because you can do this in a systematic way to learn pretty much anything https://nickjanetakis.com/blog/how-i-quickly-find-answers-to....

The code is the best manual you'll every get in my experience. There's no substitute when working on a codebase.

When I'm introduced to a codebase I'll be doing significant work on, I'll often spend hours at a time just reading the code. Start at main() and skim until you get a feel for the overall architecture, then go figure out whatever subsystems seem mysterious to you. Rinse and repeat. Makes a huge difference when making changes, because that requires reading code anyway, and you'll have a much better idea of what code to read/change.

And it will for all future make it impossible for you to distinguish official API and implementation details.

That just comes with the territory of being someone who has to understand the implementation details. No getting away from that.

Code also has the advantage of not getting out of date with what the application actually does. Invariably, documentation outside the code base often rots over time until it reaches a point it's outright misleading.

Yup, that's a good reason to keep documentation in the same repo, and to update documentation in the same commit as the code that causes the change.

One scenario where I find external wikis better is when a change encompasses multiple components and you want to present an overarching view to the user + want to refer across sections. This can be managed via something like github pages for each component but the cross referring across multiple repos adds more friction. Plus to present the overall view, something like a synthetic "doc-repo" will be needed that has landing pages that connect the component-level pages. Or we can have a wiki that does the integration by refering to component level github pages but at that point why not just do the whole thing in wiki much more conveniently.

My experience is that it basically comes down to developer discipline. A disciplined developer will update the docs regardless of whether the docs are part of repo or external and vice versa.

Imo reading gets you nowhere and is inefficient. Key piece is to add some form of self explanation or diagram to map the overall picture, since it takes a lot of repetition to understand the code flow but only hours to come up with a data flow diagram and revisit/update when needed. Even faster when someone on the team has already done it.

Maybe its just me but plain text does nothing for me so i convert it into visual elements.

> Start at main() and skim until you get a feel for the overall architecture

Man I wish that worked for Java ;-)

"My superpower is reading the manual"

That superpower is very weak, when the manual is incomplete, inconsistent or plain wrong.

Related, manuals that come with consumer products now have warnings and safety advices in 100+ language, but no usable manual anymore.

But if there is a good manual/documentation, then yes go read it.

> even if it's a small thing

How small is small? Some small fields are quite big when you factor in all global experts.

Something that you, personally, could be reasonably expected to know pretty much everything about, whether that's an internal system, a public API, or tool. It's up to you whether the topic is transferrable.

This is pretty like the quote from Thomas Huxley: "Try to learn something about everything and everything about something".

But I think people should choose topic carefully it should be fundamental, maybe it's soon unfortunately gone if you choose a trendy and short-lived tech.

Never heard that quote before. +1

"How small a thought it takes to fill a whole life!" – Ludwig Wittgenstein

My only superpower is knowing what fad is going to make a stack of cash and riding it. The only thing I've actually honestly believed in and honed recently was Go programming.

Mind sharing what fads have been the most profitable for you?

I can’t take any credit for having some omniscient insight but I was lucky enough to start Java development in 1996. It pretty much gave me a career.

Same deal, 2001 when C# was in beta.

That's worked out.

I've done a wide variety of things. I try to keep two disparate things on the go. Visual Basic between 1992-2000. C# between 2002 and 2015. SunOS/Solaris admin 1995-2002. SQL Server 1999-2010. Linux admin 1998-present. Python 2005-present. Cloud infra/AWS 2012-present. Go 2015-present. I also did some random PHP and Perl things for stupid money in the 00s. Now I'm Linux, Go, Python, cloud infra.

What I really want to do is be locked in a room with a niche project I can look after until I'm dead a this point. But that ain't gonna pay the mortgage off...

I too have recently started diving into Go in a more comprehensive way. Any ideas about why it seems to you right now is a good time to cash in on golang?

My best guess is the ascendence of Kubernetes has made reading Go rather instrumental; and as a by-product, writing Go seems much more approachable.

Not GP, but: Critical mass. Accepted in many domains as a valid first class solution. Memory safe. Has that depth of modules now that you can `go get` most things off the shelf. Easy to get a team up to speed, leading to wide adoption.

It is like the Python of statically compiled languages to me, but with way more safety rails and things you need as your code base grows.

There is just demand for it in general from what I see.

I'm not really cashing in on it. It has become my sidearm. I think that's the best way to describe it. When I want to solve a problem it's just there, trustworthy, reliable and efficient.

What it does is allow me to circumvent demotivating and productivity draining pain which is seen elsewhere which is pretty much summed up as: shitty build tools, runtime environments, libraries, containerisation, IDEs, concurrency approaches, test frameworks.

Really it's a tool that allows me to actually get stuff done.

It's pretty much what I've wanted for years: a memory safe, GC'ed C with a stdlib that wasn't conceived in the 70s.

The stdlib is really great. The things you can cross compile not worrying about glibc all day long is amazing.

Manual? One should be so lucky.

Exactly. I yearn for documentation that doesn’t require me to essentially run experiments to figure out what a library does. It is mind blowing how much time I’ve wasted in my career figuring things out that could have just been explained by accurate documentation.

Manuals used to be great when software was stable... that is new versions we're not updating online at any given moment. After a few updates these days the manual might as well be for different software totally.

Often the "manual" is just a computer-generated hyperlinked soup of tautological sentences like: this function does what its name suggests it does.

Is not that anti "antifragile" by design ? Like a being which is very well adapated to its environment: it can not survive if its environment changes.

Forget manuals, simply being able to read a stack trace puts in the top 10%.

Yeah, and being able to use Google, too...

And actually being able to post the five or six lines of the stack trace that are relevant, without the fifty or sixty that really aren't.

Those are great points. Generalizing a bit:

* Identify your superpower

What special mojo do you bring to a problem that no one else on your team can? Recognizing and leveraging your superpower can make running w/ a team of true overachievers a lot more pleasant.

RTFM (classic advice to a Unix newbie)