Documentation Survey

I’m putting together a survey which we can get people to answer about WordPress’ documentation. I’ll get it online later this week, but I thought it would be worth seeing if you guys had any suggestions for questions that you think would be useful. The aim of the survey is to:

help to create a new architecture of the documentation
help us to discover pain points
create a list of priorities for new documentation

Okay, here’s what I’ve come up with so far.

Are you:

1. WordPress user (I use WordPress to run my website/blog)
2. WordPress builder (I build and customize websites but I don’t write PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php.)
3. Novice developer (learning to write my first plugins/themes)
4. Intermediate developer (I write plugins and themes and they’re pretty good)
5. Advanced developer (I dream in PHP)

What documentation do you currently use (select all that apply):

1. Codex – guides
2. Codex – APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. documentation
3. Tutorials and guides on blogs
4. Books
5. Breaking WordPress/plugins/themes and putting them back together
6. Premium services
7. Screencasts
8. PHP docs and inline documentation
9. Forums (like wp.org or stack exchange)

How useful do you find the WordPress CodexWordPress Codex Living online manual to WordPress.org https://codex.wordpress.org/:

1-10

What types of documentation/learning do you prefer?

1. Tutorials
2. User Guides
3. Breaking stuff and putting it back together
4. Screencasts
5. Code references and API documentation
6. In-person training
7. PHP docs and inline documentation

What’s the first place you go when you have a question about how something in WordPress works?

Codex
Google
Other: [open]

What do you find most helpful about the Codex:

[open]

What problems do you face with the Codex (check all that apply):
Incomplete documentation
Out of date documentation
I can’t find what I need
Content isn’t clear
Content isn’t accurate
Difficult to navigate
Other:

What would you like to see more of:
Tutorials
Handbooks focused on specific tasks
Screencasts
Better code reference
Better inline help
????
Other:

What improvements to documentation would improve your experience of using or developing with WordPress:

[open field]

Have you ever contributed to the WordPress Codex:

Yes/No

Would you like to contribute to the WordPress Codex:

Yes/No

If you’ve never contributed to the Codex, can you please say why:

[open field]

#survey

Anonymous User 12:36 pm on May 6, 2013

First, since you have developers covered at the top (first section) did you want to include designers, just to get some more demographics? It would be interesting to see the overlap, if anything as designers use the codex too. Perhaps they would call themselves designers + beg/inter/advanced devs?
- Cátia Kitahara 12:47 pm on May 6, 2013
  
  +1 and as for the documentation I think the phpdocs are missing
  - Kim Parsell 2:34 pm on May 6, 2013
    
    “PHPDocs and reading the source code” would be a good addition to the “What documentation do you currently use” question.
    - Siobhan 12:20 pm on May 7, 2013
      
      Added PHPdocs and source code – thanks!
- Siobhan 12:19 pm on May 7, 2013
  
  Designers are covered by 3 – 5 in that list. If a designer is building themes then they are doing some development. I’m more interested in the person’s experience of code than what they do with that code.
  - Anonymous User 5:39 pm on May 7, 2013
    
    good point.
Ulrich 1:32 pm on May 6, 2013

For “What documentation do you currently use (select all that apply):”
I think support forums should be added too.
- Siobhan 12:20 pm on May 7, 2013
  
  Added
Daniel Bachhuber 5:57 pm on May 6, 2013
Thanks @siobhan! A few points of critique:
- When you mention “documentation you use” or “types of documentation”, you might want to link to examples so the respondent knows what you’re talking about.
- Unless you need the data for statistical purposes, 1-10 answer types are generally not that useful.
- I would ask “What’s the first place you go when you have a question about how something in WordPress works?”
I think the survey will work well for identifying pain points and priorities, but I’m not sure how well it will work for creating a new documentation architecture.
- Siobhan 12:23 pm on May 7, 2013
  Thanks for this
  - I’ll add links to any that require clarification once I make the survey. Good suggestion.
  - The 1-10 answer should give us some sort of idea of how well the Codex is fitting the needs of users of different levels of experience.
  - nice question. Added.
  Yes, you’re right about it not being particularly useful for creating the new documentation architecture. We’re using analytics to get a sense of what we currently have and to come up with the new architecture. I’m hoping that this survey will help us to prioritize what tasks we tackle first.
toscho 10:59 am on May 7, 2013

I use only two sources for documentation: wordpress.stackexchange.com and the source code. Might be worth to add.
- Siobhan 12:24 pm on May 7, 2013
  
  added
esmi 12:15 pm on May 7, 2013

Under “Are you:” (ie WP user type), can I suggest adding something like “WordPress support volunteer (I help out on the support forums regularly)”? Perhaps at position 3? Not all support regulars are PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. coders but their feedback on documentation could be especially useful.
- Siobhan 12:27 pm on May 7, 2013
  
  I agree that WP support volunteers would have useful feedback, but this survey is to gauge the usefulness of the Codex to WP users of differing skill levels. The first question isn’t intended to identify everyone who uses the Codex, but the level of skill of people who use it.
  
  However, this does make me think that what would be useful is a survey targeted at support forumSupport Forum WordPress Support Forums is a place to go for help and conversations around using WordPress. Also the place to go to report issues that are caused by errors with the WordPress code and implementations. volunteers on the usefulness of WP documentation. They will look at it from a different angle to users. I had thought a while back about extending a survey like this out to support people at commercial WP businesses to see what areas of WP documentation they are consistently sending customers to, and what areas are lacking.
rachel_mccollin 2:47 pm on May 7, 2013

I would suggest adding a positive question in addition to the one asking what problems people experience with the Codex. Before asking them that (and putting them in a negative frame of mind), we can ask what they find helpful about the Codex, and list the opposite of those things listed for problems.
- Siobhan 10:58 am on May 8, 2013
  
  added that but left it open. Interested to see what people say
Vid Luther 5:16 am on May 8, 2013

I’d like to add “Systems Adminstrator” as a clause as well. How to build and configure performant systems should also be part of the Codex. I believe a few months ago, there was a call to adopt a part of the Codex, we’ve been thinking of adopting the NginxNGINX NGINX is open source software for web serving, reverse proxying, caching, load balancing, media streaming, and more. It started out as a web server designed for maximum performance and stability. In addition to its HTTP server capabilities, NGINX can also function as a proxy server for email (IMAP, POP3, and SMTP) and a reverse proxy and load balancer for HTTP, TCP, and UDP servers. https://www.nginx.com/. side.
- Siobhan 10:09 am on May 8, 2013
  
  A Systems Admin handbook is definitely on my radar. I’ve been looking at the stats and current architecture and we do have an NginxNGINX NGINX is open source software for web serving, reverse proxying, caching, load balancing, media streaming, and more. It started out as a web server designed for maximum performance and stability. In addition to its HTTP server capabilities, NGINX can also function as a proxy server for email (IMAP, POP3, and SMTP) and a reverse proxy and load balancer for HTTP, TCP, and UDP servers. https://www.nginx.com/. page which receives about 9,000 hits a month. I’d love to get in touch with you once we’re ready to move on that side of things to see if you guys have time to help out with it.
Eric Amundson 12:50 pm on May 9, 2013

Yes, thanks @siobhan!

I agree with Daniel about the need for examples in the “What documentation do you currently use” section, especially point numbers 5 & 6. In fact, #5 really doesn’t seem like a form of documentation; more a style of learning. Usually when I break stuff, I end up referring to WP documentation to fix.

Maybe a bit picky, but under “What types of documentation/learning do you prefer?,” I’d clarify #1 to say something like “Written Tutorials” because there are tons of sites that provide lots of video tutorials. I understand the difference, but it could help clarify for someone for whom English is a second language.

If you were to add that, you might consider adding “(video)” after Screencasts, or list it as “Screencasts/Videos.”
Pingback: WordPress › Docs Team Update May 10, 2013 « Make.WordPress.Org Updates Make.WordPress.Org Updates

Want to get involved?

Weekly meetings

Documentation Survey

Want to get involved?

Weekly meetings

Share this: