Skip to content

WPwatercooler

WPwatercooler is recorded Friday at 11:00 am Pacific

YouTube Embed: No video/playlist ID has been supplied

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

Forums

 Mentions:

[LISTATTENDEES event_identifier=”ep43-wordpress-web-development-documentation-july-15-2013-5-51e1f3023b206″ show_gravatar=”true”]

6 Comments

  1. Conflicting hangout with client. Drat! Hope Capsule will be discussed.

    On July 15, 2013 at 10:37 am
  2. I love wp watercooler. I just stumbled across it one day while at work and looking for some help with a problem I was having. I now watch it every day (past episodes) as I develop at my full time job. I love having it on in the background. It has helped me view the wordpress community so differently and really pushed me to get involved more in the community. Thanks to this podcast, I’m looking in to starting up a WordCamp in my city for next year.

    This is a great service to the public and community. Thank you guys for taking the time out to discuss such great topics. You all seem like great people and it is always enjoyable to watch. Keep it up, and maybe consider twice a week ;]

    On July 15, 2013 at 11:15 am
  3. Hey guys,

    Just got through watching the podcast. You guys always share such great and insightful information in a truly engaging way. I really enjoy listening to all the past episodes while I’m coding at my full time job.

    Mainly I just wanted to say thank you guys for being such a great inspiration. Through this podcast alone you have motivated me to get heavily involved in the WordPress and development community. I am even considering putting together a WordCamp in my city for next year as there just is no WordPress or even development communities around here.

    I’ll be releasing my first plugin in the coming weeks so thank you again for all the insight and information you share. Keep up all the good work everyone, I’ll be tuned in next week!

    On July 15, 2013 at 11:37 am
    • Thank you for your kind comments. We try to add a bit of fun in each of them and as much education as we can stand all at the same time. I live stream the meetups at our local WordPress Meeup http://ocwp.org and have them all archives on there as well. Feel free to check them out. I also write about such things over at http://wpmedia.pro

      On July 15, 2013 at 5:08 pm
    • Evan, according to your website, you live in Philadelphia (unless you’ve moved). Do you not know about the Philadelphia WordPress Meetup Group?

      http://www.meetup.com/Philadelphia-WordPress-Meetup-Group/

      On July 17, 2013 at 9:21 am
  4. Just curious– has anyone worked on a project where the documentation was created BEFORE any coding took place, and then that resulting documentation was used as the design spec document by the developers?

    On July 23, 2013 at 7:17 pm

Leave a Comment





  
Please enter an e-mail address

This site uses Akismet to reduce spam. Learn how your comment data is processed.