EP43 – WordPress Web Development Documentation – July 15 2013
July 15, 2013, 5:23 p.m. (11 years, 4 months ago)
0 Comments
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:
* WP101
* Paid Memberships Pro
* Gravity Forms
* Twilio
* Stripe
* WPHelp
[LISTATTENDEES event_identifier=”ep43-wordpress-web-development-documentation-july-15-2013-5-51e1f3023b206″ show_gravatar=”true”]
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:
* WP101
* Paid Memberships Pro
* Gravity Forms
* Twilio
* Stripe
* WPHelp
[LISTATTENDEES event_identifier=”ep43-wordpress-web-development-documentation-july-15-2013-5-51e1f3023b206″ show_gravatar=”true”]
See acast.com/privacy for privacy and opt-out information.
No comments have been posted yet, be the first one to comment.
