dosourcenotcode

And not just options but base command names too. I wrote a tool to partially mitigate this in some cases: https://github.com/makesourcenotcode/name-safe-in-bash

Agree that long options should be used. But there is one caveat to consider: portability.

Sadly to this day not all BSD distributions have GNU style long options. And the ones that now do only got them fairly recently. So if you want portability you have to use short options as you weep with a bottle of vodka in hand.

Definitely agree with the article that engineers should be more aware of scenarios where those interacting with the systems they build have slow internet.

Another thing I think people should think about is scenarios with intermittent connectivity where there is literally no internet for periods ranging from minutes to days.

Sadly in both these regards I believe we're utterly screwed.

Even the Offline First and Local First movements who you'd think would handle these issues in at least a semi-intelligent manner don't actually practice what they preach.

Look at Automerge or frankly the vast majority of the other projects that came out of those movements. Logically you'd think they have offline documentation that allows people to study them in a Local First fashion. Sadly that's not the case. The hypocrisy is truly a marvel to behold. You'd think that if they can get hard stuff like CRDTs right they'd get simple stuff right like actually providing offline / local first docs in a trivial to obtain way. Again sadly not.

The following two links are yet another example of a similar kind of hypocrisy: https://twitter.com/mitchellh/status/1781840288300097896 https://github.com/hashicorp/vagrant/issues/1052#issuecommen...

Again at this point the jokes are frankly writing themselves. Like bro make it possible for people to follow your advice.

Also if you directly state or indirectly insinuate that your tool is ANY/ALL OF Local First, or Open Source, or Free As In Freedom you better have offline docs.

If you don't have offline docs your users and collaborators don't have Freedom 1. If you can't exercise Freedom 1 you are severely hampered in your ability to exercise Freedoms 0, 2, or 3 for any nontrivial FOSS system.

The problem has gotten so bad the I started the Freedom Respecting Technology movement which I'm gonna plug here: https://makesourcenotcode.github.io/freedom_respecting_techn...

A cool tool to be sure.

However I feel this tool is a crutch for the stupid way browsers handle web pages and shouldn't be necessary in a sane world.

Instead of the bullshit browsers do where they save a page as "blah.html" file + "blah_files" folder they should instead wrap both in folder that can then later be moved/copied as one unit and still benefit from it's subcomponents being easily accessed / picked apart as desired.

I absolutely stand by my claim that FRT is the Next Generation of FOSS for several reasons.

To begin with even now in the 2020s billions of people alive today have never once been on the Internet. Source: https://www.un.org/en/delegate/itu-29-billion-people-still-o...

Also billions more may have some kind of Internet but it's flaky. Sometimes very very flaky. They are systematically excluded from large swathes of the FOSS ecosystem.

So make no mistake, the scale of the problem is VAST. We're talking billions of people here that can be helped by FRT. Again, billions, with a B.

If all existing FOSS were transformed into FRTs overnight the world would be unrecognizably better by several orders of magnitude.

And yes we need a new manifesto/definition. FOSS standards have completely dropped the ball on this issue among several others. Do a ctrl+f for the word "offline" in either the Free Software Definition or the Open Source Definition.

Many FOSS implementations also drop the ball here. Happily some do the right thing. Sometimes deliberately which is beautiful to see. Often though it turns out it's accidental and one redesign of the site later I can't get docs for the latest version of the tool.

Oftentimes it's the small (sometimes subtle) details that make the difference between freedom and lack thereof and the FRTD exists to make sure they are covered.

Even seemingly simple things often aren't. Consider pointers, they're just a thing that stores a memory address, no big deal right, easy peasy, yet using them safely is the subject of at least several chapters in a book, and even calls for research into and implementations of safer approaches like those used by Rust.

And yes one of the details the FRTD addresses is the discoverability issue you mention with the man pages.

Say I'm a newbie that just learned there's a thing called the command line and I open my terminal. I see a Bash prompt, but I don't know what to do with it, or even that it's a Bash prompt. I don't know about the man command. I don't know about apropos. I don't know about GNU info. I don't know to try looking for info manuals if I can't find man pages. I just vaguely know from like the movies or something I have to type stuff, press enter, and then stuff happens.

I don't know anything yet. The fact that the man pages are on my system and will be available offline does all of bupkis for me at this point.

On Linux there's a man page called "intro" (and even though there's room for improving it) after which someone reads it they actually have a fighting chance of using the command line and knowing where to learn more. On OpenBSD there's a similar man page called "help" that does a similar job and starts the whole conceptual bootstrap chain. Yet nothing tells me to start my studies by running "man intro".

On Linux a one sentence message saying to run "man intro" to begin your studies of the command line would go a long way for example.

The difference between information and knowledge is often a few small bits of commonsensically placed metadata forming a conceptual bootstrap chain as well as one pointing to the chain's start. Not labor intensive on the part of implementers yet transforms the system from zero to superhero.

Or perhaps since William Shotts wrote an excellent book called The Linux Command Line, and it's licensed under Creative Commons such that it can be reproduced and included in Linux distributions, maybe there can be a pointer telling people to read that at wherever it's stored on the system instead because it's far superior to "man intro".

Again a one or two sentence message can make all the difference.

Good search and offline docs are not mutually exclusive. Grab the HTML version of Python's docs for example. You can search through them totally offline thanks to a bit of JavaScript they include.

As glad as I am that things like DevDocs and Zeal exist I feel like ultimately they are a crutch and indicative of a much larger problem in Open Source which I'm trying to address.

Now as a FOSS maintainer I don't owe anyone any particular set of features or bug fixes. BUT I ABSOLUTELY DO OWE THEM ACTUAL OPENNESS AND THE ABILITY TO STUDY THE SYSTEM PROPERLY.

Many FOSS projects frankly kneecap Freedom 1 with a sledgehammer for anyone who isn't a well off person with reliable Internet access. And I've been up to here with it for a very long time now.

For all my FOSS projects big or small my pledge is to give users complete and trivial access to the full Open Knowledge Set associated with them.

Not just the main program sources and executables, but built and source forms of any official documentation that exists.

Withholding any official documentation that exists from trivial and easy offline access in a useful form is fundamentally no better than withholding any part of the source code. Period. End of story.

My pledge for all my FOSS projects is as follows:

At the home page people within 30 seconds of having read the Elevator Pitch and decided they want to study the system properly will be able to trivially enumerate and initiate downloads for all educational information related to it whether that's source code or built forms of the documentation usable for study straight away.

How the Open Source Definition and Free Software Definition don't mandate something as common sense as this I don't know. Open Source and Open Knowledge should be for everyone, not just well off people with reliable Internet access.

Anyway that's what caused me to start the Freedom Respecting Technology movement. Thus if anything I said here resonates with anyone they should read https://makesourcenotcode.github.io/freedom_respecting_techn... to learn more.

I've been working on what I hope is the Next Generation of the Open Source movement.

See here to read about how Open Source fails in certain serious ways to be properly open and what I propose be done about it: https://makesourcenotcode.github.io/freedom_respecting_techn...

I'm also working on some FRT demo projects so people can viscerally feel the difference between FRTs and mere FOSS.

You can help by: 1. spreading the word if you agree with the ideas behind FRTs 2. helping me tighten the arguments in the Freedom Respecting Technology Definition 3. proposing ideas for FRT projects you'd like to see to help me prioritize the most impactful demos

This in my opinion is what Open Source should have been.