[PaulHoule]

It's a problem with most systems that introduce a number of new concepts, such as the documentation for the Spring framework.

One answer as a reader to deal with the circularity by reading the documentation and then reading the documentation again and then read it again until you know where everything is and then you look it up.

The worst thing about this situation is that people go look up wrong answers on programming splogs and StackOverflow and by the time you find a hugo that's been worked on for 3 years there is no rhyme or reason for how things are done because nobody has ever understood how hugo works and now you can't fix anything without risking massive breakage.

I am going through this right now with a project that I may wind up doing with hugo. On one hand I can make the case that hugo is good for my case but I can also say that I'd be happier customizing a Python-based solution or that I think the markup in hugo is less than optimal (I guess I can do anything with shortcodes but I'd really like to do visualization and unique typography in some ways... I don't want to make something that looks like a second rate substack.)

I haven't had the heart for a real battle against circularity by reading the documentation and with no definite deadline to get my hugo site up I find that other projects are tempting to think about instead...

[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 :)

[dmitriid]

> such as the documentation for the Spring framework.

Oh god, so true. It doesn't help when it's not a single project, but fifteen hundred different projects (as is the case with spring) and it's impossible to find a coherent documentation beyond the most basic examples.

[PaulHoule]

My attitude is that everything other than the core framework is crap. That is, spring-your-life-wouldnt-be-meaningful-without-this-set-of-broken-abstractions-for-some-api inevitably makes your life worse than directly engaging the API with Spring or building spring-correct-abstraction-for-api yourself.

It's a very toxic thing that Spring wasted it's brand to endorse a bunch of thin low quality packages.

[rr808]

Right its easier to switch entirely to something else. If you use Micronaut, Microprofile, Vert.x etc your life is much easier.

[PaulHoule]

It's been years since I've using Spring. Everybody who pays me to work in Java has used Guava for a while. Most of what I do on my own account is in Python or C (yuck!) or AVR8 assembler. The one Java project I am working on for myself uses balls-to-the-walls metaprogramming and code generation and is designed to enable even more metaprogramming and code generation and doesn't need dependency injection.

I spent a lot of time learning Spring in the day and I felt it filled a gap in Java in a way Guava really doesn't. I call it "configuration driven development". I was writing a large series of report generators in Python and all of them had the structure of "a little script that assembles a few objects in a library together to do a task". In the case of Java that "script" is naturally a Java class that needs to be compiled, goes through the build process, involves artifact management, etc. It's very nice that Spring provides a "general configuration file" that lets you patch together a few objects without having to compile anything.

[rr808]

> It's very nice that Spring provides a "general configuration file" that lets you patch together a few objects without having to compile anything.

Used to with xml files, now its attribute driven, just another way to double the complexity again :)

[dmitriid]

> It's very nice that Spring provides a "general configuration file" that lets you patch together a few objects without having to compile anything.

The problem is: how exact do you configure those things? How do I find which nested incantation, and in what format, is applicable to something?

[dmitriid]

Micronaut is slowly but surely going in the same direction: dozens if not hundreds separate guides with basic examples.

[oauea]

> One answer as a reader to deal with the circularity by reading the documentation and then reading the documentation again and then read it again until you know where everything is and then you look it up.

I like opening such docs twice. The first to read through, and the second to search for more info about what I'm currently reading.

[PaulHoule]

That's a good idea. Sometimes you need to explore (build your understanding of the concepts behind the system) and sometimes you need to exploit (get the answer for one particular problem).