I think the big problem with API docs is what to document. And it usually ends up with a comment per method, where you have “createFoo = creates a foo; deleteFoo = deletes a foo” and no real content. The question always becomes “well, what else?” And the real value of API docs is everything in between, the things you can’t infer by just looking at method signatures.
The following article is a good list of the other things you need to cover. It talks specifically about REST, but holds true for other API types, also. The TL;DR: what does a consumer need to know to actually use this API? How do you do auth? What are the business uses? What standards does it really follow? What are the other gotchas? What are the SLAs or other requirements for the service?
I started tech writing right around the time print was dying. My first job involved writing software documentation as a manual and as WinHelp, and it all went electronic after that. I also briefly wrote for print books about Linux and Emacs. So I have a box with versions of those manuals, and that box has bounced across the country with me, and is currently sitting in a storage space I never visit. But I always think about that chunk of print in storage, and what the end game is there. As I get new pieces of electronic junk in my life, I try to save the PDF versions of the manuals and get rid of the paper, but there’s a certain something about the print versions, too.
Anyway – Jason Scott of the Textfiles web site recently ran into a seller of manuals who was going out of business and was going to junk an insanely large archive of print books. It’s an impressive collection of old print books going back to the 30s, apparently old radio equipment or parts manuals and whatnot. The owner gave him carte blanche to grab whatever he wanted, and he’s currently stuffing everything he can into a storage space for later dissemination.
Check out the photos of the effort – this is some real print manual pornography, if that’s your sort of thing: http://ascii.textfiles.com/archives/4683
There’s also a paypal to help him cover the costs of storage and shipping and whatnot, if you want to chip in a few bucks for this massive effort to save some classic dead trees.
So at some point, Adobe Creative Cloud added a second notification to the menu bar on my Mac. There’s already one that opens the CC app, and always sits in the menu bar. And everyone else wants something in the menu bar. But Adobe started showing this second icon, with a perpetual 1 next to it, even if there were no updates, and all it does is open the first one. No combination of preference-toggling would make it go away, and neither would quitting CC.
Here’s what I had to do:
- Quit Creative Cloud.
Applications/Utilities/Adobe Creative Cloud/ACC/Creative Cloud to
- Go to the new weird menu bar thing and select Open Updater.
- You’ll see the old Adobe Updater. If you see the new CC app, you did 1-3 wrong.
- Go to Preferences and and turn off Notifications.
- Un-rename the file you changed in step 2.
- Start the CC app.
- You probably have to repeat this every time Adobe issues an update, which will be in like five minutes.
So you’ve done something, and the Notes app on the Mac won’t log in to Google anymore. It will sit and spin on a “logging in” forever.
Oh, and you’ve also just turned on two-factor auth in Google. Well, that’s the problem.
Google considers Notes to be a “less secure” app, and it won’t work with two-factor. What you need to do is create an app password, and then it will.
See also https://support.google.com/accounts/answer/185833
(Not saying two-factor auth is the problem. In fact, you should probably use it for everything.)
I resisted the upgrade to Yosemite, even though I have a pretty new mid-2014 MacBook Pro, because I’d rather let someone else beta-test things before I upgrade. When I finally did upgrade, I noticed a problem: my eyes were killing me. Granted, I’ve put a few hundred thousand miles on my eyeballs over the last few decades, but this was a sudden and marked problem.
I think there are a few things going on here, but the big two are the layout and the font. There’s a lot more brightness and transparency in the general look and feel of the layout. And Yosemite switched system fonts, from Lucida Grande to Helvetica Neue. They’re both sans serif fonts, but for whatever reason, the Helvetica taxes my eyes way too much.
I was reluctant to do anything. I hate customizing my system, because then when I change computers, I have to re-remember everything I configured, and I don’t want to be one of those people that has a freaky version of Windows 8 that’s customized to look like Windows for Workgroups 3.11 with a yellow on pink interface and the fonts in Papyrus, and if I can’t get that, I can’t work.
But, anyway, here are a few fixes I messed with:
- Select System Preferences > Accessibility > Reduce Transparency (This is true by default if #3 below is also true. This can also allegedly speed up UI lag.)
- Set System Preferences > General > Appearance to Graphite
- Select System Preferences > Accessibility > Increase contrast.
- I don’t do this, selecting System Preferences > General > Use dark menu bar and dock might be to your preference
- Change the system font back using this: https://github.com/schreiberstein/lucidagrandeyosemite
It seems like the days of cardboard key templates are over – they were a huge thing back in the old days when I started as a consultant in the computer labs back in college. Most of the cool kids would memorize everything, but more of the “returning” students would overlay the laminated cut-outs over the function keys for WordPerfect or Lotus 1-2-3.
Anyway, I’m only an occasional Photoshop user – touching up screenshots, and making dumb collages of friends’ heads I post on Facebook. So I never remember anything. Here’s a great download for Mac users of Photoshop CC. (There’s also a Windows version mentioned.)
Here’s a FrameMaker problem I had once on a 64-bit Windows machine. I don’t remember having it on my next Win7 machine, but I’ve seen it more than once.
The problem: the marker symbols were missing. These are the little “T” symbols you normally see when you insert a cross-reference or an index marker.
The solution: I did not have the
fm5font.ttf font installed. I don’t know if the installer skipped it, or I did an install when I was supposed to upgrade, or I was just holding it wrong.
You can find this font in
C:\Program Files (x86)\Adobe\AdobeFrameMaker10\fminit. Double-click it to install, then reboot.
Here’s something neat I found recently, while looking for some api docs. It’s been around for a while, but you might not have seen it if you don’t work with Python much.
Check this out: https://readthedocs.org
It’s a documentation repository, and you can find docs for a lot of Python projects there, in one searchable place. And you can host docs for your own project there, too.
But what’s neat about it is you can author your docs in reStructuredText or Markdown, and have them built for online reading, or as an ePub or PDF for download. You can import docs from source control systems like git or subversion, and use hooks to automatically rebuild every time you push code.
This is a pretty cool project with a lot of other features, and totally free, although you may want to help them out with a few bucks, too.
Here’s a FrameMaker thing that burns me once a year, usually a few hours before a release.
So, you’ve done this:
- Created a text inset file that begins with a Head1 paragraph style.
- Inserted that file as a reference in another file, at a point where the paragraph style was Body.
- Did a book update, and a blank Head1 was magically added right after the inset, causing a blank entry in the TOC. Didn’t notice this until after the book went to QA and they asked why this keeps happening.
- Went to the file with the reference, changed it back to Body, regenerated.
- Repeated step 4 for an hour or two and ended up throwing your computer out of a window.
Here’s how to get around it:
- Delete the reference in the file and start over.
- On the line where you add the inset, make that line consist of nothing but a single nonbreaking space (Ctrl-space).
- Move the cursor/insertion point to right BEFORE the nonbreaking space and do a File > Import to add the inset.
Hi and welcome to my page. This is mostly a “blog about this insane little problem so I’ll remember it in a year,” but maybe some of these factoids will be useful to you, too.
Click on any of the above to learn more about me. Or keep scrolling to see my current blog posts.