[dosourcenotcode]

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.

[imiric]

That's a good idea, but I don't see why it deserves a manifesto, or the grandiose claims about being the "next generation" of open source.

Just ship your software with documentation. This was a good practice even before open source or the internet took off. Old school closed source software used to ship with physical manuals, and good quality software often had good documentation as well. Some OSS CLI tools do have extensive manpages, yet users often don't read them in their entirety. So it's not just a matter of shipping good documentation, it's also about making it discoverable and easy to use. This is where projects like DevDocs step in.

[dosourcenotcode]

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.

[imiric]

Those are noble goals, but I think your project ignores a few important things:

- The internet has become the primary distribution channel of software itself, not just documentation. How would a user be in the position to access software via the internet, but not its documentation? They can't purchase software offline in a brick and mortar store anymore, and physical media is pretty much dead. They would need to keep the software updated on a regular basis, and downloading a few kilobytes of documentation pales in comparison to downloading hundreds of megabytes of software. So the internet really is a requirement for most software, even for those that can function entirely offline, and most developers make this assumption.

- What fraction of those 2.9B people who are not yet online would a) use traditional computers instead of tablets and smartphones, b) be interested in OSS, c) actually have a need for and the patience to read documentation? I reckon that this is a very small percentage, constituting orders of magnitude less people than the billions you claim it is. Instead, most people would be better served by using intuitive devices and software that doesn't require documentation to begin with. Smartphones and smartphone apps have made computing more accessible to more users than personal computers, desktop operating systems and mountains of documentation ever did. The next generation of computing devices will be even more intuitive, and written documentation wouldn't even make sense to new users.

- The quality of the documentation is more important than how it's accessible. It doesn't matter if I can read documentation offline, if it's incomplete, incorrect or confusing. There are no manifestos that will make developers write good documentation. This is either something they care about and put effort in, or they don't.

- The advent of LLMs is making traditional documentation obsolete. Why would any user prefer going through a bunch of documentation of varying quality to find the information they need, when an LLM could give them the right answer tailored to their query, much more quickly and in a consistent language? LLMs make knowledge more discoverable than traditional documentation. Even projects like DevDocs will not remain useful for too long. Proprietary LLMs like ChatGPT can already do a decent job at this, and other products can be trained on specific documentation. Accessibility is still a hurdle, but this too will improve with local, offline and open source LLMs, lower hardware requirements, etc. Soon there won't be a need to write documentation at all, as AI will be able to answer any functional question about software directly, which it can already do to an extent. Once it becomes better at writing software itself better than humans, documentation as we think of it today will be even less of a necessity.

So I really don't think your initiative has as much importance, or will have as much of an impact, that you think it does and will. At best, offline documentation removes a minor inconvenience for a small subset of computer users _today_. And these users already have solutions like DevDocs and, increasingly, LLMs at their disposal.