Thanks to #mdbook, I'm well on my way to finally completing my private #wiki / #docs for all things #tech: home network, desktop, mobile, code snippets and so on, guides I'm sure I'll be glad I can easily reference again someday.
It's a distillation of my experiences writing documentation for many software projects over many years. Try it for your next software project – you may like it!
I think inline #documentation is an important tool to making software readable. It makes software maintainable, encourages future development and makes it easier to join the project as a developer.
This is why I advocate for #mastodon to start encouraging inline documentation with #yardoc, requiring it for any new PRs and serving this API documentation on joinmastodon.org.
I still keep the manual of Smalltalk/V DOS by Digitalk for MS-DOS, which I used back in the early 1990s on a 386 laptop. But, sadly, I no longer have the product box and the 3.5" disk with the software.
I cannot express how important it is to write good, thorough, documentation for your projects.
How to build.
How to run.
Architecture.
Architecture decisions.
Runtime versions.
It will save you hours, days, and sometimes weeks having this written up. Your future self will love you (and maybe even toot about it).
I love reading documentation (and blogs and books) from the #rstats world. I can learn so much so quickly just by reading the docs! And they're often a joy to read!
I'm glad this community puts such emphasis and effort into high quality #documentation, and I'm grateful for all folks who pour time into maintaining it.
Are you aware of any other #communities with similar cultures about documentation?
I'm wondering not just about technical or programming communities (definitely interested in hearing about those), but any type. Birders maybe? Parts of academia? Collaborative industries?
Does anyone remember the name of the writing technique where you put each thought or instruction on a new line within the same paragraph (as opposed to continuing on the same line)?
🖥️ Alex Ellis’ new batch-actions project
📑 DevDocs is a one-stop shop for API docs
🐢 @jarredsumner announces Bun Shell
👟 Shoelace by @claviska
😮💨 Martin Heinz' DIY CO2 monitoring system
🎙 hosted by @jerod
Homelab TODO:
There is an existing pfSense guide to automatically renew an OpenVPN connection to PIA on some cadence. It also handles port forwarding for applications.
I've created a more modern idea with their Wireguard servers along with renewing the tunnel every 15 minutes and adapted to work with qBittorrent. I need to document and get this into version control somewhere.
While there were books and magazines and a few instructional videos, in the pre-Web era, if you wanted to learn a guitar part, you usually had to listen to recordings and figure it out for yourself.
These days, you can just google the name of the track and there's a good chance that somebody already transcribed it as guitar tablature, and posted it online.
A big time saver, for sure. But on the downside, it means that guitarists who predate that tend to have much better ears.
@jasongorman I’ve noticed that I favor consulting official or direct #documentation more than my less-seasoned #programming colleagues who reach for #StackOverflow. I find that the former often reveals cleaner and more general solutions than the FAFO pragmatism of crowdsourcing.
Does anyone know what is happening with the Misskey project? It seems they changed the docs site once again. Similar to the last change, many of the links are leading to not found message or lack additional details.
It looks like they are now using Nuxt. Why migrate to new doc site if most of the info are not ready? Confused
The advice for writing better software manuals in this article, published in the May 1983 issue of BYTE magazine, is still useful, assuming software manuals are still produced. The article noted that software with good manuals sold better, which makes sense.
Burden of #proof is always tricky when a complex, poorly understood and documented piece of software need to be validated. This might encourage higher standards of #documentation and #verification to be maintained, as well as the necessary logs that enable assertions to be checked.
Corollary: If I have to grep your source code for the error message to find out what it is and where it's coming from, you need to rewrite that error message and add more #documentation.