I was just reading a post by Hairy Larry about documenting software, The Document is the Program. He talks about the specification, the programmer documents, the end user document, and online help. There is so much to do! My own programs suffer from much the same deficits and I think I’m doing way better than most programmers out there, as far as I can see. Perhaps that’s because I’m a stubborn programmer and often come back to my own code and sadly I’m nearly always humbled by my past self. I’m often amazed at the things I wrote when I was younger. And then I curse myself if I find that the documentation is lacking. Over the years, my programmers documentation has improved and the cursing has gone done. This is good.
As for end user documents, all I can say is that the situation feels a lot better than a few years ago. Why is that? I personally think that’s because of a little genius idea by GitHub. By deciding to display the README per default, and by allowing programmers to use all sorts of markup to write those README files, including GitHub-flavored Markdown, these files have turned into actual, readable documents. Expectations have gone up, and quality has gone up. It’s great.
I also see more projects now moving their documentation to Read the Docs and similar sites, but I’m not so sure that this particular tendency has improved my own sense of better documentation. My guess is that at the same time, the use of `man` pages has gone down, the use of `info` manuals has gone down, so now you have to be online to program and keep searching for information online, or you use a separate tool to download the online help in order to have it available.
I was reminded of this, recently. I just couldn’t find offline Python documentation and as a Perl person I was used to the idea that every package I downloaded came with its own set of `man` pages. Oh well.
Anyway. I love the `README.md` files because people have accepted that their README file is the first thing visitors see, the most important piece of information everybody will read, and so most projects have a good README file. This is so much better than in the old days.
��#Documentation
(Please contact me if you want to remove your comment.)
⁂
python -c ’help()’
– RadomirDopieralski 2018-03-05 17:41 UTC
---
README display: that is an interesting observation!
I wish that Hackage would nudge Haskell library authors to write examples of how to use their libraries (like the SYNOPSIS section in Perl POD) in a similar way.
I’m used to using perldoc(1) rather than man to look up Perl documentation, pydoc3(1) fills the same slot for Python.
– Adam 2018-03-05 19:52 UTC
---
I learned something new today! Thank you very much, both of you.
– Alex Schroeder 2018-03-05 22:20 UTC