[andrelaszlo]

I'm working a bit with GCP infrastructure lately and I find Google's docs very well-written, but suffering from a bit of the opposite problem. Many docs are written as how-tos for very specific scenarios, often the most basic setup thinkable (which makes sense!). If you're trying to understand the abstractions in order to see what will make sense for your own project, it's a difficult way to get the full picture. :D

It seems like good docs often have two types of articles:

1. Short and clear definitions of terms, abstractions, resources, etc. 2. Self-contained how-tos and overview type articles on common issues and ways to use the product.

If it's just one or the other, or both mixed up, I often find it frustrating.

[Nagyman]

Django has some of my favourite docs, organized incredibly well:

* Tutorials * Topic guides * Reference guides * How-to guides

https://docs.djangoproject.com/en/4.0/#how-the-documentation...

[Starlevel001]

Sphinx-based docs are usually excellent due to how easily it lets you flow between tutorials and references.

[PaulHoule]

Sphinx has a nice facility for blending "Javadoc" style documentation with discursive explanations which is used to great effect in the Python docs, but used that way it doesn't automatically generate all of the automatically generatable documentation the way Javadoc does so often you end up with lots of content missing.

[teach]

There are, in fact, four types of documentation[0]:

1. Tutorials 2. How-To Guides 3. Explanation 4. Reference

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

Edit: and of course this is a top-level comment down below.

[PaulHoule]

Ideal documentation has interlinked sections that serve different purposes.

For instance right now I am writing up a report on a research project I did a year ago (shouldn't have waited) and now facing the problem of running the scripts. Some of them are well documented but some aren't. Whether it is you or somebody in your pod who has to do it, there is a need for "runbook" documentation so you can do tasks such as building and deploying software correctly and easily.

There's also a need for reference documentation that explains everything systematically, even that tends to need multiple forks -- for the Spring framework there is all of the Javadocs, but the Javadocs are not sufficient to explain the concepts that Spring is built around.

Then there are the pedagogical examples that make doing something tricky look easy and link the implementation to the concepts involved.

I'd point to the Python documentation as a particularly good example. I never feel tempted to look outside the official Python documentation to look up anything that's involved in the core language.

Somehow I don't find the documentation for pandas to be effective, largely because I perceive the ways of doing things in pandas to be idiosyncratic, so I find myself looking up answers on random web sites a lot more often than I feel comfortable with. If I used pandas everyday I might feel differently, but I usually end up doing a burst of data analysis work for a few days and then go a few months w/o using pandas.

[shadowgovt]

The problem Google runs into is a lot of the systems they build in GCP are written that way too: with a specific set of user-stories in mind, and an "I guess we'll see what the community does with it" attitude for any use cases they didn't anticipate.

This might be a symptom of the problem domain itself.

[andrelaszlo]

Yep, had this problem several times already.

Look at the fancy load balancer, it can do traffic splitting and you can attach a security policy (waf) to it! Oh wait, you can't do traffic management stuff with the "classic" (legacy) LB, switch to the new one that's still in "preview" (beta). Oh wait, it doesn't support the waf yet. Etc etc.

Another one is some sort of hard-coded service users that must be in place to run things, for example in App Engine. If you delete it, you can't just create a new one with the same permissions, you must undelete it... but only if less than 30 days have passed (!).

All of this is documented of course, but spread out all over the place. The thing about deleting service users isn't (as far as I know) made clear in the IAM docs, for example. The only place I found it was in a howto for the App Engine Python environment: "Using the Default App Engine Service Account".

I share the author's frustration, if it isn't obvious :)