Our great sponsors
-
hitchstory
Type-safe YAML integration tests. Tests that write your docs. Tests that rewrite themselves.
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
textual
The lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.
-
-
cheat
cheat allows you to create and view interactive cheatsheets on the command-line. It was designed to help remind *nix system administrators of options for commands that they use frequently, but not frequently enough to remember.
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
For those interested in the concept of having permanently up-to-date documentation with screenshots I built this testing framework based upon the idea that good documentation can be a autogenerated artefact of good tests:
https://github.com/hitchdev/hitchstory
I built a macOS commmand line util to take window screenshots or videos https://github.com/xenodium/macosrec Window screenshots are mostly covered by macOS built-in app, but videos are not.
Mostly grew out of a desire to post screenshots on my posts and projects.
I often wish I could see how some projects look before I install them (but they often don't have screenshots). I'm doing my bit with my projects, I hope.
The Textual project has a lot of screenshots in its documentation. These screenshots are built with the docs, so they are always up to date.
https://textual.textualize.io/
When you're learning something for the first time, it can be hard to know what mental model you need to have to be effective with the tool.
Some documentation is reference material. With reference material you might navigate the reference material in a particular traversal to get what you need to do what you want.
But at the beginning of your journey, you need to be taught a "flow" an expected pattern of operation to build up the right mental model of how an average session with the tool works. For programming this might be the edit file, compile, run, debug loop, or TDD or IntelliJ's build and deploy. Or a CI system commit, push, deploy, promote cycle. Or kubernetes kubectl edit, apply.
I opened the "dining philosophers TLA+" example and ran it - this seemed to be an affordance of the TLA+ Toolbox GUI which was straightforward to understand.
But then I tried to use the tool with my own. I interpreted the existing code of the dining philosophers and tried to make my own ringbuffer model.
It took me a while that I needed to update this screen to put in the following details that I have filled in on the screenshot:
https://github.com/samsquire/assembly/blob/main/screenshots/...
You have to put your entrypoint in the "temporal formula" and then put your model arguments on the right hand side.
I was able to piece together the operation of this tool by piecing together various reference details together, it wasn't until I saw that screenshot I referenced in my OP that I realised I needed to do that step to get the PlusCal code to update the TLC code that follows it. I was wondering why it didn't work until I saw that screenshot.
cheat.sh [0] has been a godsend when the man pages are too dense and I just want to use the tool and move on with my life.
[0] http://cheat.sh/
Looks like bro pages is archived and they recommend https://github.com/tldr-pages/tldr or https://github.com/cheat/cheat
Looks like bro pages is archived and they recommend https://github.com/tldr-pages/tldr or https://github.com/cheat/cheat
You should never, EVER use animated GIF screenshots of people typing in a CLI as your only source of documentation. Here's an egregious example that was posted yesterday:
https://github.com/ofek/pyapp