Hacker News new | ask | show | jobs
by grantjgordon 3536 days ago
The Rethink docs truly are incredible.

Do you have any guides or books you recommend for writing good documentation? What software did you use to produce Rethink?

Sorry to see Rethink go.

1 comments

The documentation is all maintained in Markdown and built with Jekyll, so it's pretty straightforward. There were a few custom Jekyll tags. For writing, I used the venerable Mac editor BBEdit; obviously any text editor can do a fine job here, but there are some subtleties in BBEdit I liked. Its "open file by name" command can open multiple files with the same name at once, for instance, and its find/replace functionality goes above and beyond the call of duty.

For books/guides, it's hard to say. Find documentation you like a lot and think about what makes it good--the organization/taxonomy is really important to pay attention to, as well as the tone (formal, conversational, weird, etc.). As shocking as this might be around here, the _Microsoft Manual of Style_ is useful as a specifically technical guide, and it's good to have a relative recent edition of the _Chicago Manual of Style_ kicking around as a reference. And, just being familiar with standard grammar and punctuation rules is important. A lot of people aren't. (A lot of people who aren't still think they are.)

Hahaha. That is surprising! Thanks for the helpful advice.