Writing great documentation: you need an editor | Hacker News Reader

Writing great documentation: you need an editor

jacobian.org

46 pointsjacobian15 comments

I recommend the Economist Style Guide. My friends who are print journalists regard it highly. A slim novella of the guide is available for offline reference.

"This guide is based on the style book which is given to all journalists at The Economist." http://www.economist.com/research/styleguide/

I was hoping this was going to reveal the secrets of which editor makes docbook not suck.

"Change your margins" is one trick for reviewing your own text. The author says it makes it easier to be impersonal.

I wonder if changing your highlighting scheme would help you review your own code?

My favorite trick for self editing is an extension on the "change your margins" trick. My print writing/publishing cycle involves typesetting, so even if it's not going to be used for my final target I typeset things in LaTeX and then edit them there. Wide margins and a totally different presentation from my monospaced text editor makes detachment much, much easier.

Usually it annoys me that I edit my blog post with narrow (editing HTML) margins, then see it at full width after I hit "post".

As he points out here, even a little trick like that does make it easier to edit. And I do manage to find a lot of my flaws very quickly. So I guess I'm benefiting from this trick.

Slightly o/t: Does the font on his site look awful to anyone else? In opera, the site looks like this for me, which is horrible. I have to mash the readability script bookmarklet to read it: http://imgur.com/ODnjY.png

Slightly off-topic, indeed :)

But yes, I have the same problem. I'm using Opera too, and use shift+g to disable stylesheets when reading that page. (You need to enable single-key shortcuts for this to work)

Another Opera user chiming in, same problem. On Windows. Thanks for the shortcut.

The CSS declaration is:

font-family: 'Sabon LT Std', 'Hoefler Text', 'Palatino Linotype', 'Book Antiqua', serif;

Which of those fonts are you actually seeing?

Unsure (I'm not great at eyeballing fonts), is there an easy way to check?

The screen shot you posted doesn't obviously match any of the listed fonts, but if you can find your OS's list of installed fonts, just check which of those you have installed.

It's kind of bizarre that you're defaulting to an italic font when the site doesn't seem to request italic, it may be that you have only the italic variant of some font installed.

Seems to be Palatino Linotype (that's the first one of the font-family my OS has available). Not sure why Opera has decided to italicise it though, as the installed font looks fine normally.

Palatino being a pre-computer font also has a tendency to be hurt by screen aliasing a lot. If you can activate some sort of anti-aliasing/smooth font layer on your computer even the italicized version shouldn't look so painful.

He makes some good points, but you don't necessarily have to ask before editing open source docs. For example, if they're publishing in a wiki you can pretty much assume its ok to jump right in and start editing.

"Writing great documentation: you need an editor"

I use Emacs.

(Sorry, couldn't resist.)

Reply on news.ycombinator.com