I may write a book for beginners to learn programming in a general sense, not about a specific language.

Then once the beginner gets some experience, he/she no longer needs to read a book as fluffy as The Go Programming Language. He/she should be able to grab the language reference or cheat sheet to learn the language quickly.

The Go Programming Language sins:

• It spreads important points among texts without emphasis so I have to use a highlighter to mark them by myself.
• Most of the time, it talks the easy topics that any experienced developers can learn in half an hour, totally, but I'll have to go through the whole text to make sure I don't miss anything important, especially those language features that are "similar to another language but not the same".

An Ansible issue: Documentation: Add warnings about using facts based hostvars['hostname'].

Ansible subelements documentation is not so clear:

• It doesn't explain where the notations of 0 and 1 come from.
• Nor does it explain whether there is 2 or even more.
• Someone must ask a question to understand how it works: https://stackoverflow.com/q/41908715/630364

• [x]What nobody tells you about documentation

I don't know how DDD can relate to this project but there might be some intrinsic connection between them because they are both about documentation:

• Readme Driven Development
• On Documentation-Driven Development
• Documentation-driven Development
• Documentation-Driven Development
• Documentation-Driven Development

TODO:

• No Silver Bullet: Essence and Accidents of Software Engineering
• Yes silver bullet by Mark Seemann

Coding Horror: If It Isn't Documented, It Doesn't Exist

In another article, Learn to Read the Source, Luke, the author said:

And because writing for people is way harder than writing for machines, the documentation will continue to suck for the forseeable future. There's very little you can do about it.

Well, the document-shredded project aims to improving this.

CMake 3.21.3 tutorial does not provide a link to the accompanying source code, or at least the link is very difficult to find unless I search it in Google (and the repository is not even the top results in Google search results). However, the tutorial itself refers to the code frequently and makes me frustrated not to be able to read the code while reading the tutorial.

FYI: The code is here.

Description

This issue collects the cases of "loss of knowledge": Because programmers come and go, when a project has been ongoing for quite a long time, the knowledge of some part of the code may get lost along the way.

It needs further evaluation to see if this is caused by lack of good documentation, but usually that means the implemented feature is not important in practice so nobody really cares.

Goals of good documentation:

• Minimize the time that new readers need in order to grasp the related topics.

Good documentation should include:

• Background: Why is it?
• History?
• Cookbooks: task-oriented
• FAQ
• Security Concerns
• Main Body of Knowledge
• Comparison of similar technologies: pros and cons
• How (for developers)
• Ecosystem: How this technology is related with other upstream/downstream technologies
• Examples vs abstract description
• Best Practices

Good documentation tells EVERYTHING about the software. However, this is almost impossible because chances are the developers themselves do not have a total grasp on the software: it's just too complex.

The action plugins are run in the context of the user that launches the playbook so it is not affected by --become. Is this documented anywhere?

• Maybe I can ask on the #ansible channel.

See this Stack Overflow question and one of the comments.

Actually, it turned out to be that React Router v6 is quite different from the earlier versions and they published the documentation for v6 here. Technically, they didn't do anything wrong. However, they probably should have mentioned in the documentation website that v6 is quite different so the users should pay attention to the version they are using.

HTTP caching

Today (2021-05-04) I tried to learn about "Heuristic Freshness Checking". This page refers to RFC 7234 Section 4.2.2, but I find this section doesn't provide any specific example so it's hard to understand how it is calculated by simply reading the text.

Some other references I can take a look:

• https://stackoverflow.com/a/31852117/630364
• https://stackoverflow.com/a/27938965/630364
• https://stackoverflow.com/a/39160589/630364

Doc smell: infinite links which means one resource provides a link to another resource which provides a link to a further resource but none of them explain the things clearly enough.

Vagrant CLI documentation is not so clear.

Very immature idea but basically:

• We write code in the way that's easier for sharing the knowledge: future developers should not spend huge amount of time to learn it.
• Documentation generation should not rely on the particular format of comments because comments can be out-dated.

Description

amixer documentation may not be good enough. Take this question for example:

Why do we supply pulse as a parameter in amixer command?I have noticed if I doesn't supply pulse parameter to amixer command it doesn't work and throws error.

However, the owner of the answer didn't reply it. I have the same question. Unfortunately, I don't seem to be able to find the answer with some quick search (e.g., amixer(1)).

Another question is: What is the Master control in amixer? There doesn't seem to be an answer about that. amixer(1) has an example that says:

amixer -c 1 -- sset Master playback -20dB

will set the master volume of the second card to -20dB. If the master has multiple channels, all channels are set to the same value.

which seems to suggest that Master is a special control that covers all the available "channels".

The article A close look at ALSA has a section "ALSA concepts" which explains "cards" and "devices", but it doesn't explain what the Master is.

Anyway, I think many open source projects need to build better documentation in order to transfer knowledge.