documentation, then and now 

To manipulate the light-bar, use the UP and DOWN ARROW keys or type a letter or
number in the option you wish to highlight. To highlight the first option of
the menu, hit the HOME key. To highlight the last option of the menu, hit the
END key. You'll notice that if you hit UP ARROW key when the light-bar is at the
first option of the menu, the last option will become highlighted. This wrap effect
also occurs when hitting the DOWN ARROW key when the light-bar is at the last option
of the menu. To select the current highlighted option, hit ENTER . To exit SCFG,
hit the ESC key.

An excerpt from the Synchronet BBS SysOp Documentation, copyright © 2006 by Rob Swindell and released under the GPL

re: documentation, then and now 

This may seem like an over-documented bit of functionality to modern eyes.

It's not; you're just used to seeing massively under-documented functionality.

Show thread

re: documentation, then and now 

@djsundog Proposal: a personal computer is not "good" unless its documentation is heavier than it.
Follow

re: documentation, then and now 

@bhtooefr @djsundog

> Proposal: a personal computer is not "good" unless its documentation is heavier than it.

I like your thinking, but I'm not quite on board. Under your rule, a desktop from the 80's needs more documentation than a modern ultraportable laptop—and *far* more than a tablet. That doesn't seem quite right.

How about this:

> Proposal: a computer is not "good" unless it has more documentation (measured in pages) than RAM (measured in MBs).

re: documentation, then and now 

@codesections @djsundog I think that misses the mark, too - for instance, a lot of stuff from the heyday of personal computing had less than 1 MiB RAM, but a one-page manual would have been terrible.

And even scaling that down to pages per kiB... the Apple-1's 8-page manual was arguably insufficient (you'd at least want a 6502 datasheet to go with it, I'd argue) despite the 4 and 8 kiB RAM configurations.

re: documentation, then and now 

@bhtooefr
@bhtooefr
Going the other way, 16GB = 16384 pages. I'm not convinced that's a useful amount of text, although perhaps the VMS technical writers would disagree. ;P
@codesections @djsundog

@codesections @djsundog

re: documentation, then and now 

@vertigo @bhtooefr @djsundog

> a lot of stuff from the heyday of personal computing had less than 1 MiB RAM, but a one-page manual would have been terrible.

> Going the other way, 16GB = 16384 pages. I'm not convinced that's a useful amount of text,

Both good points—linear scaling is too aggressive. I still think there's something to requiring more powerful computers to more more docs, not *less* (which is the trend).

Maybe proportional to the log of RAM?

re: documentation, then and now 

@codesections @bhtooefr @djsundog I think spending 50 to 100 pages per functionally usable component of the computer would be a good starting point. Vis-a-vis, the C64/C128 Programmers Reference Guides. Describes everything from how to program in BASIC to how to use the low-level chips, even to how to build your own expansion cartridges. They even included circuit schematics for the computer as a whole.

Sign in to participate in the conversation
Fosstodon

Fosstodon is an English speaking Mastodon instance that is open to anyone who is interested in technology; particularly free & open source software.