EP43 – WordPress Web Development Documentation – July 15 2013 – WPwatercooler

Today’s topic is about Documentation. Documentation for a website, plugin or theme is an important component of a project. It allows the uninitiated to work with your code on either the web side of things or adding to your existing code. Documentation enables your customers to understand how to use what you have built for them. Commenting your code isn’t enough, not everyone reads and interprets PHP and Javascript so taking the extra effort to explain how to use what you built will save people time, frustration and racking up support tickets for you to deal with. On this weeks topic of WPwatercooler we will be discussing documentation of all aspects. How does the customer expect the documentation to be and how a web developer can save money in spending the extra time writing, updating and cultivating good documentation for their customers.

-== 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


-== Mentions:
Paid Memberships Pro
Gravity Forms

Jason Coleman – Paid Memberships Pro Developer, Software Architect

Suzette Franck- (mt) Media Temple Developer

Chris Lema – Chris Lema Developer, Software Architect, Marketer

Natalie MacLees – Purple Pen Productions Developer, Designer

Siobhan McKeown – Audrey Capital Developer, Designer, Engineer, Software Architect, Marketer

Robert Neu – FAT Media Developer, Marketer

Andrew Norcross – Reaktiv Studios Developer

Sé Reed – Sé Reed Media Developer, Designer, Marketer

Jason Tucker – Tucker.pro Developer

Steve Zehngut – Zeek Interactive, Inc. Developer

Jason Tucker

Jason Tucker

Web Developer at Tucker.Pro
Jason brings 15+ years of hands-on experience as a web developer and systems administrator at large corporations and businesses in the fields of healthcare, manufacturing, technology and entertainment. Specializing in PHP coded sites utilizing WordPress. Jason owns and operates Tucker.Pro a WordPress web development company in Whittier, CA. He is also the host of WPwatercooler a weekly WordPress YouTube show and podcast
Jason Tucker
Jason Tucker
Jason Tucker

Leave a Comment

You must be logged in to post a comment.