Comment by travisgriggs | Hacker News Reader

Comment by travisgriggs | Hacker News Reader

Isn't the real time most software documentation started going down hill was as the internet became the primary way of distributing and updating software?

When software distribution was tied to hardware mediums, it froze snapshots in time, and the documentation thereof could be snapshotted with it (to varying levels of success). Even needed to be.

But once it all became primarily net based, it meant the software was always fluid, in motion. Imagine the tech writer approaching a developer now days:

"Explain how this works to me"

"Ok, right now, it works like this, but we're working on a revised version for next year..."

"Sigh. Ok, explain that to me too."

"You bet, but make sure and check back with me before you publish, because some things might change yet."

It's an irony, that the original dream of "the web", a distributed documentation system, is rendered ever instantly out dated in the realm of software because of the distribution models it eventually enabled. Unintended side effects I guess.

As a side anecdote, consider man pages for venerable established Unix commands. Now consider the man pages for newer Unix utilities. IME, the newer features are often under documented and require going to code portals to get detailed/up to date answers.

Depends on the version of Unix. OpenBSD considers documentation to be a first class feature of the operating system, and new functionality isn't considered ready for merging and release until the documentation is complete and high quality.

It speaks to the contradictory nature of software development as it's currently practiced, I think.

"What does the software do?"

"What do you want it to do? We can add that."

"Well, I want to be able to access my old work in a few years, and maybe use it in another program."

"I pinky promise that that will happen, and we will make that happen, after we get through all our other customer requests."

It's not exactly a new problem that we keep updating software - "bells and whistles" is an old piece of hacker jargon - but there isn't a sense of definite publication now, because there are so many methods of blackboxing in the way, and that's been allowed to take place through the promise of "one more thing" and "surprise and delight" - we only really put up with it through a sense of increasing hype and spectacle. If you have a really firm grasp on what you want the computer to do, you can eliminate just about every application program.

Most line-of-business software has always been more service than product, and I think we're right to embrace that. If you shrinkwrapped an accountant and sold them as they were, 5 years later they wouldn't be much good for anything. The computer is a bicycle rather than a taxi, it needs active involvement rather than passive use.

I worked on a project in the early 90s to figure out a way to distribute updated docs along with software updates. At the time, the software updates were shipped on CD, etc. We could ship the docs in WordPerfect AND Word formats. But that wasn't very palatable. We talked with WordPerfect about this portable document format thing they were working on (Envoy?). And we talked to Adobe about some sort of similar thing they had in mind. We could ship the document reader for Mac and Windows on the CD with the docs.

We also explored the idea of perhaps putting the docs as postscript files on an internet server with a ghostscript app and some instructions on how to ftp the files or something. That all seemed so close to right, but not quite feasible.

We weren't even considering the internet for software distribution. It was all an idea to provide our customers the latest and greatest documentation. But the internet was not established enough to let us refer customers there for practical use. And ghostscript was some hokey concept from people in some GNU movement or something and wasn't close to production quality.

Three years later we lived in a completely different world.

I think you're right. I also think there's often an attitude of "break things and move fast". Take a look at three.js, they break stuff every 3-4 releases which makes all the tutorials on the net out of date. They explicitly state they don't care one wit about backward compatibility.

It's also possible that it's not just that things are distributed on the net but also that the speed of development as accelerated. Some of the is undoubtedly due to the net (easier access to lots of resources/sample/libraries) as well as easier to collaborate and a ton more people doing it.

Reply on news.ycombinator.com