Hacker News Reader

Comment by ComputerGuru | Hacker News Reader

I am with you on this. It seems to be a new trend: “show users how to do a hello world” which was disregarded in the past... but somehow that turned into “instead of providing real documentation” rather than “in addition to.”

It’s not just GitHub. There’s a language I (and the rest of HN) love that has adopted “story format” for documentation but is missing real, hard technical documentation apart from method-level codedocs. It’s nice for building momentum but it leaves you unable to find a central location with an architectural documentation of the system.

View on HN

I read an article[0] on HN[1] recently — it talks about the different types of documentation. To quote it directly:

"Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all."

I agreed with its premise — I've found things that only have "story format" docs (i.e. explanation / how-to guides) to be really frustrating. On the other hand, if all that's available is a deep and highly particular technical reference, it's really difficult to get started sometimes.

[0] https://www.divio.com/blog/documentation/

[1] https://news.ycombinator.com/item?id=21289832

What is the difference between a tutorial and a how-to guide?

Level of previous knowledge assumed, tutorials tend to be more "starting from zero", and scope, guides tend to have a narrower focus.

if you read the link he gave, it has a really good description of each...

but to summarize...

A tutorial: - is learning-oriented - allows the newcomer to get started - is a lesson

A how-to guide: - is goal-oriented - shows how to solve a specific problem - is a series of steps

And as an example, Don't list how to install node.js, npm packages and ENV settings in your HAPI server tutorial

A tutorial is to an integration test what a how-to guide is to a unit test.

Think of how tos as recipes for different scenarios

Someone please tell the Google Cloud Platform teams this. So many hello world examples which reek of, "I was told to write documentation but I really hate writing documentation". I mean this in good faith, I think writing documentation for a product you don't actually use is a miserable experience and I hope they can find a better balance...

Writing documentation also seems to be a task you kick out to your junior developers that you'd rather not give more critical assignments to, which is backwards as can be.

Oh god yes, so frustrating

Android docs feel the same way, with a side of "eh, just make the interns do it".

If there's one documentation that I hate with my gut, that is GCP documentation. Like wtf is going on there. Just to give you an example of how horrible it is, just check their Vision documentation: https://cloud.google.com/vision/docs/

They have quick starts, tutorials and how-to-guides. How are even those things conceptually different at all?. And their reference is just a list of their methods like if I knew out of the box how to use your API. Like, what the heck. Just tell me how to talk to your API in simple terms. How hard is it?

"To use the CGP vision API there are two ways to authenticate and connect. 1) REST 2) SDKS" and then just explain to me how to do it simply.

Don't ramble like if this was the fucking Iliad. Go straight to the point and organize your information better.

It's possible that I'm jaded by non-existing documentation, but skimming over the docs in your link, this actually looks like an example of good documentation*

The API reference in particular you pointed to has a top-level description + linkable reference to each individual method / resource along with brief description. AND, for older versions, as well as a description of "objects" used in the API. I guess it would have been nice to also have a sandbox playground, like some of their other APIs do, but this one is fairly good?

Just curious, what's an example of great API in your mind?

*(possibly not in-depth enough, but I wouldn't be able to tell as a newbie).

In this case, google cloud vision, it seems like the docs are fine. It’s the platform that’s confusing because it requires too much ceremony to get started.

GCP documentation is the worst I have come across so far. The GCP documentation seems to have multiple personalities. It is as if the different parts of the documentation were written by different teams in different corners of the company.

I have to often disregard the documentation and get into the gcloud (their Python-based CLI and API) to understand what the heck is going on and their CLI/API code is no good either. Layers and layers of abstraction in their code only to make some REST API calls. The amount of over-engineering and abstraction that is present in their Python code would put even Java SimpleBeanFactoryAwareAspectInstanceFactory developers to shame.

It's not their documentation that is bad, it's the architecture. Too many layers, and things glued together. Where you need to make additional abstractions just to make sense of it all, ending up with a million LOC just to copy something from A to B.

For example integrating support for Google Drive took months, where I ended up using a third party solution, and users are met with a big red warning about my app now being unknown. And the file system is laggy. Compared to integrating Dropbox which took three days and just works. Google Drive probably have thousands of pages of documentation. While Dropbox have one or two.

It's a moat.

Being fairly new to Python the "story format" of the documentation is one of the most frustrating things.

"This package is really good. Here is an example. This feature is cool! This other feature solves a common problem. Here is a list of some of the functions."

I agree with this.

I haven't done any substantial Java work in probably 8 years and I still miss the JDK docs.

I'm hitting the same problem a lot with a bunch of things.

Concourse CI is the one I'm running up against this today - I'm taking over a partially built installation which has all sorts of hard-coded config environment variables that I'm trying to figure out their purpose.

Their documentation has basic getting-started stuff[1], but doesn't list all the config variables and their use. It's open source, so I cloned the repo, but they don't directly reference the environment variables there, either.

Compare that to, say, Ansible's documentation - it exhaustively lists all the options[2] and what they're used for, with links to other related documentation.

[1] https://concourse-ci.org/concourse-web.html [2] https://docs.ansible.com/ansible/latest/reference_appendices...

(Concourse co-creator/OSS lead here.)

Our CLI hasn't really aged well and that's something I'd like to address soon - probably going more in the direction of config files instead of flags/env vars. It'd be a lot easier to document with a proper schema. Thanks for the feedback and sorry the experience is still pretty rocky!

Awesome, thanks.

Honestly the whole application seems pretty good - but everything is focussed on more hello-world stuff, which is great for getting going on my machine - not so great for running it for real.

Whether you use environment vars or a config file, I don't mind - one benefit environment vars gives is that setting CONCOURSE_BIND_IP to the instance's IP is relatively simple, eg on AWS:

CONCOURSE_BIND_IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4)

If it's a config file then I need to update that before the application starts, which is more fiddling.

Yeah that's a good point. There are definite trade-offs to going for only one or the other. If there's a nice way to support both without too much maintenance overhead, that'd be my preference. There are a few popular Go libraries which support that, like https://github.com/spf13/viper - which we'll probably consider switching to as part of a general CLI overhaul.

For a long time now we've been primarily focusing on the core design, concepts, and architecture at the expense of documentation and introductory material and outreach - we've never had a dedicated technical writer, so documentation is really best-effort. Now that the dust is settling on our roadmap I feel a lot more confident in increasing our focus on onboarding, operability, and developer/user experience in this coming year. :)

I assume you’re talking about Go here?

I wouldn't think so, docs in Go look very terse to me, not at all "story mode".

Maybe Rust or Clojure...?

Rust has books [1] as well as the usual terse API docs [2], so that also seems unlikely.

[1]: https://doc.rust-lang.org/stable/book/

[2]: https://doc.rust-lang.org/std/

Unless something has changed very recently, Go docs aren't story-format.

Possibly Typescript. Try finding documentation for the bundled "Record" type. It seems you're supposed to just know how to use it already.

https://www.typescriptlang.org/docs/handbook/utility-types.h...

I've heard the same typescript feedback from coworkers. Another commenter already linked to the official docs, I always link them to https://github.com/sindresorhus/type-fest#readme which has links and docs of the built in types and can be installed for more.

I have yet to find a straight answer on how `declare` actually works in the Typescript docs. I had to go to Stack Overflow to learn what it's for.

The TS docs basically just say "use declare to declare [thing]" over and over, and it's only mentioned in the handbook on a page that doesn't seem to be listed in the handbook menu anywhere.[0] You have to search for it and wing it, because the search result for this just says "By Example." Notice that there is no article highlighted in the handbook menu on the left like there would be on any of the pages listed there.

[0]: https://www.typescriptlang.org/docs/handbook/declaration-fil...

So, what's the language?

Reply on news.ycombinator.com