3 ms·
An interesting perspective is most of the suggested docs were written in the last couple years, at most. I think you'd benefit by finding retrocomputer people
by VLM 4y ago
An interesting perspective is most of the suggested docs were written in the last couple years, at most.
I think you'd benefit by finding retrocomputer people and asking them about docs they've seen to find the best technical writing of the century.
I don't have a short list of IBM Mainframe docs, but those are probably "the best documentation money could create" in the 50s-70s.
Easily second best would be the DEC TOPS-10 Software Notebook Series which in my experience was a set of 20 binders and in one shelf it contained all you need to run a major 80s minicomputer operating system including apps.
What 80s DEC documentation did VERY well, was every doc was planned out intelligently and in detail by actual users to make sense to a professional sysadmin on the job. Unlike "sales/marketing" driven docs, the software notebook series TRULY understood its audience of professional sysadmins. I also feel that 80s DEC documentation had the best intros in technical writing I've ever seen. Intros are underrated and the author(s) need to make a "contract" with their reader before throwing detail at them. Take for example, volume 6 or so of the dec-10 software notebook series which has the ALGOL programmers's reference guide with the best intro ever. "This is where you start" should be the most carefully designed and written chapter of the docs, not a filler chapter. In summary, don't skimp on outline and don't skimp on writing a real intro.
Personally I like some of the Tandy/Radio Shack Z-80 manuals. Perhaps the extended basic manual for the model III, or the 6809 assembly book they resold are the pinnacle of late last century technical writing for a more general audience.
Retrocomputing is a fun hobby that extends far beyond technical writing critique, obviously.
- Someone 4y ago> which in my experience was a set of 20 binders They came in binders because, regularly, you’d receive a packet of new pages, sometimes a few, sometimes tens or even hundreds, with instructions on where to insert them in the binders and what pages to discard. git pull is a tiny bit easier ;-)
- jimbo9991 4y agoI agree with you, but let's be honest, if you aren't already well exposed to that world then those docs are going to scare the shit out of you. They definitely are not "easy reads". The extent to which you are looking for something reference like and intensely technical vs. something to ease you into a new stack will determine whether you appreciate IBMs mainframe docs. They definitely don't fit the mold of what most people expect from documentation nowadays though. If anybody wants to see what they look like, type IBM zOS v2r5 indexed collection into Google (the most recent batch of docs). I don't really have any one in particular that I would recommend starting with, because none of it is going to make much sense if you are new to that world. The ABCs of Systems Programming Redbooks are probably a better introduction than the main documentation, although those volumes are a little bit more out of date.
- tuatoru 4y agoI agree with this. The Postgresql docs are adequate--not outstanding, just adequate--by the standards of the mainframe and minicomputer manuals of those days. Nothing else today even comes close[1]. There are so many things you just have to try. 1. OpenBSD makes a good attempt, but the project is under-resourced.