Hacker News new | past | comments | ask | show | jobs | submit login

Everyone at RethinkDB was incredible to work with.

Thanks for showing everyone how to write amazing documentation

Thank you! (Really. I'm RethinkDB's documentation writer/editor.)




I have always wondered why there isn't a tech company that just does kick ass documentation for companies. Seems like a small group of people who make kick butt stuff in this area.

Really, you did have fantastic documentation, as the original said. Kudos.


Thank you. And...hmm. That's an interesting question.


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.


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.


There is a company, yc in fact http://readme.io/


It doesn't look like readme.io actually writes the docs; they just make tools for writing docs.


<3




Consider applying for YC's Spring batch! Applications are open till Feb 11.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: