Linux's contemporary filesystem mount API went without documentation for six years — latest man-page package finally adds content for 2019 code

ezst036 said:

The man pages are not really user documentation either, they're "techie" documentation and usually for more-techie-than-average techies at that.

IBM documentation tends to consist of both a reference and a user guide. The user guide is intended for beginners and others that want an easier explanation and do not need the details. The reference is more technical. I think that if I had a choice of one or the other, I would choose a reference. It is possible to write a user guide from a reference but it is not possible to write a reference from a user guide. I think it is important that the man page documentation include all technical details necessary for the use of the software. Other (educational) documentation could be developed from that.

Ezst036 said:

From no man to man to YouTube.

I think you misunderstand what documentation is. YouTube is great for tutorials but useless for documentation.


Now with AI it is possible for an AI system to analyze source code and create specifications. Documentation is much like specifications; the documentation could be developed from the specifications. Also, it is hopefully easier to read specifications than the source code. This might be an excellent opportunity to explore such solutions. The following is what Perplexity AI says on the subject.

Https://www.perplexity.ai/search/i-read-an-article-saying-that-SntxdNRaR.WqUlBeldUdug#0

Good code does document itself but only to a point. Writing readable and understandable code should be a given but it should also have comments, at minimum what the function takes as input, what it does and what it returns as output and then adding on comments for any unusual or less understandable bits of the code.

Then there should be user level documentation above that, they don't care about how it is implemented, they only care about what each function does and how to use it. A good example I have found is the STM32 Cube drivers, they bundle a HTML user documentation of the drivers. It includes things like public functions, variables and macros as well as private functions, variables and macros. In order to use it the public sections are often enough, clear documentation on data structures and function definitions and what they do.

I wouldn't class it really as a user guide as it isn't quite as clear as would be needed for that, but it is clear enough if you know what you are doing.

Yes code should be readable and understandable but that doesn't mean it shouldn't have comments and documentation. Comments can speed up someone's understanding of your code and it takes much less time to just write a comment explaining your thought process rather than many people trying to figure out why you did what you did. Then documentation is even higher level and is for people who don't care how your code works, just that it works, which I would say is the majority of open source software users.

In my opinion neglecting comments and documentation is just laziness. How often do programmers say that when they go back to code they have written previously they basically have to decipher it from scratch? Or at the very least need to take time to understand it? That should tell you something. It shouldn't need you to go right through all the code in an open source project to understand why it is done that way or what each function does. As with any engineering discipline other than software engineering, logs and explanations are essential and often non negotiable. You need proof that you thought through it. In current software engineering you can essentially say that this random piece of code that I just spewed from my brain passes all tests so it is fine.

I honestly believe that readable and understandable code being enough is not completely true, yes it might be enough to understand the code, but if your colleague comes to check or change something then it likely ends up taking more time than just writing comments as you go. In programming the time consuming it is not typing, it is thinking, so typing out your thought process really doesn't slow things down and can actually increase your productivity. It is like that saying that the best way to learn something is to teach or explain it.

-Fran- said:

So I half agree with your semantic distinction to call the man pages "techie user documentation", but never forget they are still "user" level documentation for a very specific target audience.

Fair enough.

Sam Hobbs said:

The user guide is intended for beginners and others that want an easier explanation and do not need the details.

Yeah. So often projects create detailed documentation which have their place, but they're not the best source for beginners.

Conor Stewart said:

Good code does document itself but only to a point. Writing readable and understandable code should be a given but it should also have comments, at minimum what the function takes as input, what it does and what it returns as output and then adding on comments for any unusual or less understandable bits of the code.

I don't entirely agree with this, because you seem to mandate comments for more mundane parts of the code.
This risks the user of the code assuming that the code does what the comments say, rather than examining the code and learning what the code actually does.

There many automated ways to check code for correctness, there are none that I know of to check comments for correctness.

So if you think you need comments for routine features try to think how overall code structure can be improved. For example, you can use the type name for the input or output variable as documentation for what the variable is meant to pass. You can have documentation for the module or whole project that specifies which dimensions the variables use.

You should only add comments when you really cannot express yourself through the code, or when there is some external consideration. This should not happen too often.

You could also a tool like "doxygen" to keep user level documentation for public functions in the same file as the code. This has the advantage of making it easier to keep two different texts in sync, but you can still have errors where the function documentation says one thing, while the code does something different.

Whats the "Something something good code comments itself."?!

ezst036 said:

This is a pretty big bugaboo and it is kinda widespread within the Linux realm.

This is pretty much true of the man pages themselves as well. The man pages are not really user documentation either, they're "techie" documentation and usually for more-techie-than-average techies at that. Software developers become a special breed, gaining the ability over time more to speak to their computers but that comes at a cost: losing the ability to speak less and less to normal humans.(Note: This is definitively NOT to be read as an insult.)
From time to time I see someone ask how to do X and the response is RTFM. Not realizing, I read the man! It didn't help. So that is why I came here now to ask you to break it down human to human for me instead of the awful man pages.

I think this may at times lead into a larger problem of keeping the myth alive that Linuxes are all still terminal based systems and nobody ever heard of a GUI. Go to YouTube and how many times do you see someone with a Linux desktop and the very first thing they do is open a terminal when right there on their menu, you can see it. Click the button. Click the button. WhY aReNt YoU cLiCkInG tHaT bUtToN rIgHt ThErE i CaN sEe It In YoUr ViDeO! I don't want to see your terminal I want to see you click the button. Just click the button. It's right there!!! ARG! Why are you intentionally making this more difficult? Sigh.

Well, there goes my little rant for the morning.

Improper documentation, it's a problem at all Linux levels. From no man to man to YouTube.

Complaining that the man pages for C API usage is only suitable for "techies" is a little misdirected. A non-techie will probably never need to know this, or even see any man pages. Most Linux distros have enough user level documentation for GUI only users; ones that don't, probably shouldn't be used by such users. Desiring all documentation to cater to all types of users is a perhaps not a great idea, and in some cases, a waste of resources.