Most people don't think linguistically, we have way more conceptual thinking. What makes it difficult is we rarely realize we are thinking conceptually when writing because these concepts occur automatically and we don't notice it.

In school this lead to a lot of difficulties for me, one in writing those comments out for other people to understand, but the other seemed to be that when reading the average statements used in education for teaching I could map the same strings of language to multiple and sometimes conflicting statements because of the inexactness of the language used.

It turns out explaining concepts while leaving little room for different interpretation is hard.

I find that writing this documentation is both a "muscle" and gets better with experience.

e.g. as you both write documentation and see yourself or others use it, you start to get a feel for what people tend to understand and how to communicate it.

You can also do "dog fooding" where one person or group writes the docs and then other people follow them. If you iterate on this quickly, you can get to really good docs in a short amount of time.

That's why having a long shell history is so great, you can just scroll back further to get more context, because it really captured everything.

The one thing I have found that really helps here, for self-directed documentation, is to write it for a modified version of yourself.

You may still be the audience. But you will be four or five years older, shit will have gone on in your life, you will have more to remember, you will be tired, you will have less patience, you will resent being forced to do archaeology on yourself, and have a dim view of the irresponsible young scamp who thinks he has an excellent memory that you are right now.

Write for that person and your documentation will be better.

(As you may be able to tell, I am now that person. And I fear there are two more cycles of this to go)

My boss gives me shit regularly for not remembering things. He doesn’t seem to understand that when you manage environments in all three clouds, storage arrays in four different countries from different manufacturers, four on prem virtual clusters, Active Directory, entra, etc that you can’t remember everything all the time if you haven’t touched it in a while.

I started a daily journal when my team’s workload got to be so much that we can’t remember everything. It helps, but even going back to it weeks later there were things I did not write down because I assumed I’d remember them later.

I’ve since gotten better at being more comprehensive, and trying to think in the “how to make a sandwich” way of instruction. I’m not being condescending to my future self, I know my future self has too much shit to mange to remember it all.

My new test is to ask an LLM questions about the documentation and see if it gets correct answers. I wonder if this will become a common QA step for the docs at some point, it's very useful for finding gaps in the docs or things that are unclear.

That's true.

But, I also see a lot of posts that have comments like, "How am I supposed to know what Gleam does when I don't know what a Tribble is? The blog doesn't explain anything! How can someone write an article and not explain these terms that they use so much?"

And the linked blog article is hosted in the Daily Tribble News section of www.tribbleworld.com.

It’s a bit funny how normalized this is. Surely being more clear would provide some market advantage?

Or perhaps not, if folks who need a Tribble for their Fork achieve instant enlightenment upon reading the marketing copy.

It also happens with marketing emails, or (worse) waiting lists: "great news, we're live!" -- Who the heck are you again?

I recently had this experience with hotjar [0]. I _already use hotjar_ and still struggled to understand the page lol

If somebody from hotjar/cintentsquare sees this, I’d prefer if your page was more straightforward about the name change. Maybe try “we’ve rebranded to content square”

[0] https://contentsquare.com/hotjar/

I hate marketing websites especially for developer products.

“You no longer have to florp, now you can vorp!”

Big numbers, random charts. 10x 100x 200x!

Who is this for? Just make the docs the home page.

I was confused by your mention of "Gleam", but I suppose it is just a generic name, not referring to Gleam [0], the functional programming language, as the latter is an example of a project that focuses on concise and minimalist documentation (btw, its README is just a reference to the website).

[0] https://gleam.run/

(Updated the text as the downvotes indicated people misunderstood what I wrote. I agree about OP's observation)

Now imagine living in San Francisco where you see this shit on every bus ad and billboard. Except these days they’re all “Tribbling. With agents. gleam.ai”

I think I read somewhere (and in any case it matches my experience) that the first user will catch 50% of the problems and that with 5 users you can catch close to 90%. So human testing is not just invaluable, it's pretty cheap for the benefits it brings.

There's the famous quip that Steve Jobs hated focus groups. What people miss is that he (and Apple overall) was heavy on UX testing.

I was also going to post "this sounds like usability/user research".

But I guess we all re-discover things when we need to.

The biggest issue I've seen with tech docs is often expert users of a given tool or product are enlisted to write the docs, because of their expertise.

But then ironically they end up writing those docs for an audience that shares their level of expertise, rather than for the intended audience.

So you end up with lots of assumptions or leaps of logic in the docs that the intended audience can't follow.

I'd wager this is interesting, seems there are a lot of users here building things on the side (or main projects) that need clear UX if they're anything like me, they don't have that UX background to know the best practices. I know I just clicked your link anyway...

Yes very much so and thanks for the link.

The other variant is "Foo is an alternative to bar". While it could work in the niche you are in and it is totally fine to not target people outside of it, it could be really hard to get into.

There are a number of (newish) AI projects on GitHub whose README make zero sense. I would read it three times but still have no idea what it does.

If your project is aimed at average developers yet someone with professional software engineering experience like me cannot understand it, sorry I'm not going to use it.

> using un-introduced abbreviations (bonus points for abbreviations that have common meanings, e.g.: EG, NB, IE, ETC)

Every company should give their new employees a list of in-company invented words and abbreviations, so that you don't search for them online and then feel like an idiot for not being able to find them. Especially when the older employees use them as if they are common knowledge.

Could have used extra 1 centimeter to format the comment's list properly. :)

> go the extra 10 cm

Going to steal this

This sounds exactly like UX usability testing. Sit down with someone and watch them work through whatever process you’ve created.

It’s normal to compensate them for their time.

Normally though you don’t modify it after each participant. But for something very niche like following a README (as opposed to an e-commerce flow targeted to the general population) it might be fine, if less rigorous.

I'm glad the author mentioned this particular learning. Even if you do enjoy reading your own jokes, many other people will find them at best annoying and at worst confusing. When you add in people from other language/culture backgrounds the risk/reward of jokes gets even worse!

There was a famous conflict over rms's joke about the abort() function in the glibc manual[0], which said:

> Proposed Federal censorship regulations may prohibit us from giving you information about the possibility of calling this function. We would be required to say that this is not an acceptable way of terminating a program.

I think that joke illustrates nicely what I mean: it would only have made sense to people in USA, and would have just confused others. Even those who understood it would - IMHO - most likely not appreciate it being in the glibc manual. People don't read manuals to be entertained - they read them to find out as quickly as possible how to get their work done.

[0] https://lwn.net/Articles/770966/

> "They were the ones who caught the mistakes that no spell chequer could."

I thought that maybe "spell chequer" was the valid British term, which would be interesting, so I searched but it isn't. It turns out that the joke here is that "chequer" is a valid British word, so a word-based spell checker won't flag "spell chequer", so it's self-referential. I see why people found his jokes actively confusing.

When deciding on a style for documentation, I typically draw the line between tutorials and references. The linear top-down flow of an introductory guide lends itself well to inserting additional context throughout it even if not completely on-topic, while in an API or hardware reference you generally want to keep each section reasonably self-contained, trivially searchable for (minimizing false hits by carefully choosing keywords) and readable independently of the others. I have found the literate programming approach [1] of writing entire tutorials as code to work pretty well for this purpose, which I've used to great effect in some of my pet projects [2].

[1] https://en.wikipedia.org/wiki/Literate_programming

[2] https://github.com/spicyjpeg/ps1-bare-metal

> My jokes aren't funny and are actively confusing.

Well, I found that sentence in the post was very funny ;-)

isnt this what footnotes are for?

Being short and concise is usually the better way.

I tend to be too verbose in writing as I want to explain the context in more detail, but short, accurate, concise is best. Many developers fail at that too, though. Many projects do not have working examples. That annoys me the most. It sends a message of "I don't care about new users learning how to use my project".