Hacker Newsnew | past | comments | ask | show | jobs | submitlogin
The Vicious Circle of Documentation (hezmatt.org)
3 points by akerl_ on Feb 15, 2015 | hide | past | favorite | 2 comments


Answering questions with links to the specific documentation in question is a useful technique. It reinforces that there is documentation, and helps vet the quality of it. It often means that the doc creator is also its reference librarian, but that's not all bad.

otoburb's suggestion to have a comprehensive internal search capacity is an excellent one.

Another element I strongly endorse: creating documentation on a system which allows for creating ePub or other eBook formats. The number of times I've been stuck in a color or server closet trying to scan docs either on a console or laptop session, or worse, a smartphone -- except that the network's down -- is too damned high.

An eBook reader and recently-updated set of pubs is a lifesaver.


>Do you have any other ideas for how to encourage readers to read, and for authors to write?

Ensure that your internal system has a consistent and accurate search engine that can index across multiple different file types. The article implies that documentation is written in a single, monolithic format (e.g. PDF, text, Word, blog posts, internal social media posts, etc.), but relevant content is often fragmented not only across mediums but in their refinement from rough notes (sometimes mere meeting minute mentions) to externally-consumable form.

Encouragement for authors to write was addressed in the blog pots, although I've found that taking the time to praise specific groups and authors for their documentation is typically quite effective.




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

Search: