We’re celebrating Foreman’s Birthday today, organized by Netways!
Right now, Maximilian and Aneta are taking the stage with an exciting presentation:
"Foreman Documentation: Year in Review & We Want Your Input!"
They’re diving into what’s been improved over the past year and how you can help shape the future of our docs.
And yes, whoever uses #discord for #documentation and #versioning instead of a goddam #git [doesn't have to be @github / #GitHub or @gitlab / #GitLab or @Codeberg / #Codeberg or even @gitea / #Gitea - just use any git
and write down your documentation in a useable format like #Markdown or goddamn ASCII plain text FFS] should be banned for life from #coding, working in #IT or contribute to #FLOSS.
Every CMS user hits a wall — unless there's great documentation to guide the way. Joomla's documentation is written by volunteers and for the community. Whether you're documenting how to build great sites or correcting typos, every edit improves the experience. Want to make Joomla better without touching code? This is your moment.
Find out how you can help to get better Joomla user documentation! https://magazine.joomla.org/all-issues/june-2025/how-to-contribute-to-user-documentation #Joomla #CMS #OpenSource #Documentation
Divine Documentation
Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination.
Image of a nebula taken by the Hubble Telescope.In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.
I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist.
Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.
Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library.
So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte.
* Those dastardly Tuftes are always making me learn some kind of grammar.
Wait, you mean you're supposed to resolve the merge conflicts BEFORE publishing the docs?
Huh.
Microsoft Learn Contributor Chatmode | by Luke Murray.
https://luke.geek.nz/azure/microsoft-learn-contributor-chatmode/
Today BookStack turns 10 years old!
In this blog-post we celebrate this decade of BookStack with a Q&A, while also diving into the stats & finances of the project:
https://www.howtogeek.com/why-i-actually-like-reading-linux-documentation-over-other-systems/
Documentation written by the people who made the software, not some PR/Marketing schmuck, that's honest about it's flaws instead of insisting "There are no bugs in Ba-Sing-Se" Not having to worry about Documentation disappearing, or needing to buy a new copy of the book every couple of years. What's not to love?
The alternative Godot docs viewer of our member @rokojori has been updated to 4.4!
https://rokojori.com/en/labs/godot/docs/4.4/
It also includes nodes of his very promising Rokojori Action Library (https://rokojori.com/en/labs/rokojori-action-library/overview), but if you ignore those it is also a very nice alternative docs viewer for vanilla Godot!
Astro Docs is redefining Must-See TV... well, for docs
Tomorrow on Talking and Doc'ing:
- Fixing an Astro Docs SEO issue using Starlight's new `routeData`.
- Writing docs for a feature that doesn't exist (and that we don't yet even know how we're going to implement) to drive its development!
Subscribe to the @astro YouTube channel and be notified when we go live (Thurs 9ET / 14:00 CET)
Love the feeling of updating documentation. Once a month I have a team meeting where we walk through technical IR tabletops.
Today it was a brainstorming exercise on how to hunt behaviors and information over multiple tools, in case one goes down. And assuming I died. Work with my team to get creative and understand how tools work, especially with expertise missing.
This is a good exercise for team robustness and education.
And lets me take vacations mostly uninterrupted. Only 2x in 10 years, and both of those uninterrupted trips were in the last three years. Yee haw.
@thomasfuchs
Honestly I learnt every #tech skills of mine because of the #passion. Sooner or later we get these #short #term and #long term #purpose.
But if someone's going for #AI #coding for the sake of #Job / #Career might not #sustain if things get hard. That's why I #suggest people to #learn #organically developing their mind #map through #logics.
I use AI for understanding the #documentation and #debugging purposes not for a entire #mental #model.
I do it for #education not #production.
There's an art to writing code comments. Too many and nobody reads them. Too few and future developers curse your name. Find the sweet spot.
FreeBSD has a handbook that's actually worth reading:
https://docs.freebsd.org/en/books/handbook/.
It’s exhaustive, community-maintained, and official.
@PierreZ Nice #blog. All the bad and ugly are not because #Nix #NixOS is hard, but it's because it does things #differently than others. And the #language in and itself is not that #difficult, but have to agree that the #documentation situation is not that great which is being solved by many #community initiatives like #videos in #youtube, #blogs, #sites etc
But once someone got the gist of #best practices way to do things, then it'll be easier to #learn and #adopt.
#Development #Guides
Writing comments in front-end code · “Don’t forget that future-you is a teammate.” https://ilo.im/1656cf
_____
#Programming #Coding #Comments #Documentation #Collaboration #WebDev #Frontend #HTML #CSS #JavaScript
How JSDoc Saved My Dev Workflow, by (not on Mastodon or Bluesky):
https://spin.atomicobject.com/how-jsdoc-saved-my-dev-workflow/
#israel #palestine : #war / #gaza / #dailylife / #civilianwarvictims / #media / #documentation
„How do you cook, charge a cell phone, go to the bathroom, or get to sleep when you’ve lost everything and are living in a displacement camp? Ahmed Abu Kmail, a 38-year-old Palestinian cameraman, is our source of information in this diary from Gaza, where the simplest acts of daily life have become an unimaginable obstacle course.“