Why are some companies so bad at providing documentation?
If you’re a developer and you’ve spent many hours writing code working with or creating API’s, and you want to bring on a 3rd party and have to explain the code, it can take as long to explain the code as it was to write the code. It can ultimately defeat the purpose.
On the flip side? If you employ someone to do the documentation they come with a different perspective to you. As a developer you’ve been immersed in the code for a long time but they will look at it with a fresh set of eyes. Often the developer will struggle to explain it to the non-developers, user documentation writers and novice users. An outside writer is like having a translator for you. The turn “geek” into “normal language.”
Developers really don’t like writing documentation. It’s a lot of work and a time suck. As things change, your documentation is immediately out of date.
How to get better at creating documentation:
There needs to be a differentiation between developer documentation and user documentation. The developer can pass off their own documentation to the write who then creates user focused documentation.
Jason Coleman talks briefly about the process used by Paid Memberships Pro: Once they’ve finished development and put out a heavy release, they shut down development and move into a documentation period.
If you’re finding that you get more user questions from your documentation, your documentation might be the problem. Test it out on a novice developer.
Documentation is no substitute for a good user experience. If you’re back end is a total mess, documentation doesn’t matter a lot. It doesn’t fix bad code.
What about video documentation?
Downside: screencasts take a long time to produce something professional
Upside: If you don’t care about it being professional, you can create something quickly that should answer basic questions. It’s good for many end users, however no everyone wants to spend the time watching a video. Sometimes they just want to get into the doc, find their answer and get out.
Different types of documentation:
Inline documentation with your code
Inline documentation and help info around elements in the GUI
Free documentation as a download
[LISTATTENDEES event_identifier=”ep43-wordpress-web-development-documentation-july-15-2013-5-51e1f3023b206″ show_gravatar=”true”]
Editor’s Note: Transcriptions of episodes are created with a mix of speech recognition software and human transcribers, and may contain some grammatical errors or slight deviations from the audio.