Siobhan 9:42 am on June 7, 2013
Tags: Codex ( 19 ), survey ( 3 )

The Codex survey is closed and the next…

The Codex survey is closed and the next stage is to go through the responses. We’re going to do this by user type:

Drew – Advanced Users
Eric – WP Builder & novice dev
Siobhan – Intermediate dev
Jerry – WP User

Please post your results here by Friday 14th June. We’ll be using the results along with other research that’s been going on to do a workshop on the first morning of the docs sprint.

A few notes for the reviewers:

Use the filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. at the top to filter by your assigned user group I’ve edited your access so you just get the results for the user group you’re looking at.
Remember that if a respondent provides a particularly insightful answer you can click on the report number to the left of their answer and read through that person’s individual report.

If there’s any other questions you feel should be added to the report, let me know in the comments.

Outline for Report

User Type:

Learning preferences (please list in descending order, noting the percentage):

Notable answers listed under other:

Top three places to look for an answer to a question (list in descending order, noting the percentage):

Are there any other places that these users are regularly looking for answers (make sure you check through the “Option option” answers)?

How useful is the Codex to this user group?

What sections of the Codex do these users find most useful?

What are the main problems these users face with the Codex?

What documentation would these users like to see more of?

Based on your review of this survey, do you have any general observations about how this user group is making use of the Codex and documentation more generally?

Based on your review of the survey, what recommendations would you make specifically about the WordPress CodexWordPress Codex Living online manual to WordPress.org https://codex.wordpress.org/ that would help these users?

Based on your review of this survey, make three recommendations for improved documentation that would serve these users:

Contributing to WordPress Docs

What percentage of these users have contributed to WordPress Docs?

What percentage are aware that they can use their WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ login to edit the Codex?

How can we make it easier for these users to contribute to WordPress docs?

#codex, #survey

Eric Amundson 2:22 pm on June 7, 2013

Thanks for posting this outline, Siobhan! It’ll make the analysis and reporting a lot easier. 🙂

Will post my results ASAP.
Eric Amundson 11:52 pm on June 9, 2013
WordPress CodexWordPress Codex Living online manual to WordPress.org https://codex.wordpress.org/ & Documentation Survey Results

User Type: Novice Developer

1. Learning preferences (please list in descending order, noting the percentage):
1. Written Tutorials 30%
2. User Guides 18%
3. Screencasts and video tutorials 16%
4. Breaking stuff and putting it back together 16%
5. Books 8%
6. Asking questions on support forums 7%
7. In-person training 5%
8. Other 2%
Notable answers listed under other:
- StackOverflow
- StackOverflow Chat
- Function Reference
Most amusing:

wordpress is the hardest app out there

2. Top three places to look for an answer to a question (list in descending order, noting the percentage):
1. Google (or other search engine) 36%
2. Official documentation 29%
3. Support Forums 19%
3. Are there any other places that these users are regularly looking for answers (make sure you check through the “Option option” answers)?
- StackOverflow (6 write-ins)
- StackExchange (6 write-ins)
4. How useful is the Codex to this user group?
- 7/10 – (353 Answers, Sum 2587, Mean 7)
5. What sections of the Codex do these users find most useful?
1. Function Reference 31%
2. Theme Development Documentation 20%
3. User Guides 12%
4. PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party Development Documentation 12%
5. WordPress Lessons 10%
Notable “other” answers:
- I tend to just search it, so don’t differentiate between parts
- There were several users that were confused about resources saying things like:
  - Unknnown, what is Codex?
  - didn’t really know about the others
  - where is the old list of references?
6. What are the main problems these users face with the Codex?
1. Incomplete Documentation 20.67%
2. Content isn’t clear 18.39%
3. I can’t find what I need 17.99%
4. Difficult to navigate 16.11%
5. Out of date documentation 14.77%
6. Other Option 8.59%
7. Content isn’t accurate 3.49%
Notes from other answers:
- The number one most requested thing is: More examples
- Need Spanish, Turkish, German, Russian
- pages for different languages are messed up in a common menu – that’s terrible. A user will only search in one language or another, and in two as a maximum (native lang + english lang)
7. What documentation would these users like to see more of?
1. Written Tutorials 28.91%
2. Better Code Reference 28.79%
3. Handbooks focused on specific tasks 19.07%
4. Screencasts 13.89%
5. Better Help in the WordPress Dashboard 7.32%
6. Other Option 2.02%
8. Based on your review of this survey, do you have any general observations about how this user group is making use of the Codex and documentation more generally?

Often searching from Google or within the Codex to hopefully find clear, simple documentation that includes examples.

9. Based on your review of the survey, what recommendations would you make specifically about the WordPress Codex that would help these users?
- Clearly communicate docs organization. What’s in Codex vs Handbooks
- Easier navigation
- Return more recent articles first (weight by time & relevance)
- Consistent formatting
- Allow doc only search
10. Based on your review of this survey, make three recommendations for improved documentation that would serve these users:
1. More code examples & use cases
2. People want written documentation in easy, plain English*
3. Easier navigation
Contributing to WordPress Docs

11. What percentage of these users have contributed to WordPress Docs?
- 10%
12. What percentage are aware that they can use their WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ login to edit the Codex?
- 39%
71% said they’d like to contribute.

13. How can we make it easier for these users to contribute to WordPress docs?
- Give clear, easy instructions on how to get involved. Should be in the form of a quick – 1-2-3 Easy Get Started Doc.
- Clear guidelines / rules
- Provide easy list of to-dos / articles / things that need attention
- Make it less of a time investment
- Easy way to report content that’s inaccurate, needs updates, etc.
- Pimp email list so people sign up and get reminders & updates.
- Give new contributors quick, constructive feedback to make them feel “part of” the WordPress community.
MVPMinimum Viable Product "A minimum viable product (MVP) is a product with just enough features to satisfy early customers, and to provide feedback for future product development." - WikiPedia comment:

Give me some time to get over the last attempt and then I will try again. Remind me in a month!”
Eric Amundson 2:13 am on June 10, 2013

Hey Siobhan,

In your outline of questions under Contributing to WordPress Docs, you might want to include:

“How many in this group you like to contribute to WordPress documentation?”

Also, please let me know if there’s anything you’d like me to dig into more, provide results differently, or otherwise change.
Eric Amundson 2:50 am on June 10, 2013
WordPress CodexWordPress Codex Living online manual to WordPress.org https://codex.wordpress.org/ & Documentation Survey Results

User Type: Builder

1. Learning preferences
1. Written Tutorials 28%
2. User Guides 23%
3. Screencasts and video tutorials 19%
4. Breaking stuff and putting it back together 13%
5. Asking questions on support forums 8%
6. Books 5%
7. In-person training 3%
8. Other Option 1%
2. Notable answers listed under other:
- Examples
- Snippets
3. Top three places to look for an answer to a question (list in descending order, noting the percentage):
1. Google (or other search engine) 39%
2. Official documentation 29%
3. Support Forums 22%
4. Are there any other places that these users are regularly looking for answers (make sure you check through the “Option option” answers)?
- StackOverflow (1 write-ins)
- StackExchange (2 write-ins)
5. How useful is the Codex to this user group?
- 7/10 – (152 Answers, Sum 1057, Mean 7)
6. What sections of the Codex do these users find most useful?
- Function Reference 26%
- User Guides 16%
- WordPress Lessons 15%
- Theme Development Documentation 13%
- Troubleshooting Information 12%
- FAQs 9%
- PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party Development Documentation 7%
- Other Option 2%
Notable “other” answers:

forum, if you removed the questions that are never answered. It clutters the place up and wastes time

Obviously, the top hits need to be summarized somewhere using layman language, maybe with screenshots that are updated as WP versions change (I know! a lot of work, I am a willing helper)

7. What are the main problems these users face with the Codex?
- Incomplete Documentation 18.53%
- I can’t find what I need 18.21%
- Content isn’t clear 17.57%
- Out of date documentation 15.97%
- Difficult to navigate 15.65%
- Other Option 10.86%
- Content isn’t accurate 3.1
Notes from other answers:
- Again, more examples are high up on the list
- Need better language support
- Going along with ‘content isn’t clear’ many talk about the lack of simplicity or need for more, or better description.
8. What documentation would these users like to see more of?
- Written Tutorials 27.62%
- Screencasts 20.72%
- Better Code Reference 18.78%
- Handbooks focused on specific tasks 18.23%
- Better Help in the WordPress Dashboard 11.05%
- Other Option 3.59%
9. Based on your review of this survey, do you have any general observations about how this user group is making use of the Codex and documentation more generally?

Like Novice Devs, this group seems to use search to find docs in hopes of finding a easy walk-through tutorials, snippets, and practical examples they can follow and learn from.

Builders seem significantly more likely to want video tutorials and significantly less interested in code reference.

10. Based on your review of the survey, what recommendations would you make specifically about the WordPress Codex that would help these users?
- Make format easy, simple & consistent
- Include practical examples or use cases
- Embed, or link to, helpful screencasts, but always have a canonical text version.
11. Based on your review of this survey, make three recommendations for improved documentation that would serve these users:
- Simplify language
- Include examples and use-cases using tutorial format when appropriate
- Follow consistent, easy-to-follow format
Contributing to WordPress Docs

12. What percentage of these users have contributed to WordPress Docs?
- 5% (8 people)
13. What percentage are aware that they can use their WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ login to edit the Codex?
- 34% (52 people)
56% of people would like to contribute

14. How can we make it easier for these users to contribute to WordPress docs?

This group lacks confidence that they have anything to contribute. Some flat said they’re unqualified.
- Provide easy instructions on how they can get involved
- Provide task lists
- Provide polite, quick feedback.
MVPMinimum Viable Product "A minimum viable product (MVP) is a product with just enough features to satisfy early customers, and to provide feedback for future product development." - WikiPedia Responses:

Eschew obfuscation.

It’s scarey to think that someone like me can contribute. I would prefer that you aim for a higher quality.
Siobhan 1:32 pm on June 13, 2013
User Type: Intermediate

Learning preferences (please list in descending order, noting the percentage):

Written Tutorials (30%)
User Guides ( 21%)
Breaking Stuff and putting it back together (20%)
Screencassts (10%)
Books (7%)
Asking Questions on support forums (6%)
In-person training (2%)

Notable answers listed under other:
- reading the source code
- meetups/conferences
- reading developers’s blogs
Top three places to look for an answer to a question (list in descending order, noting the percentage):
- Google 35%
- Official Documentation 31%
- 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. Docs 12%
Are there any other places that these users are regularly looking for answers (make sure you check through the “Option option” answers)?
- stack exchange
- youtube
- reading the source code
How useful is the Codex to this user group?

Out of 10
- Mean: 8
- Median: 8
- Mode: 8
So pretty useful

What sections of the Codex do these users find most useful?
- Function Reference 38%
- Theme Dev Docs 22%
- PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party Dev Docs 20%
What are the main problems these users face with the Codex?
- Incomplete Docs 33%
- Out of date docs 18%
- difficult to navigate 13%
What documentation would these users like to see more of?
- Code Reference 43$
- Written Tutorials 27%
- Handbooks 14%
Based on your review of this survey, do you have any general observations about how this user group is making use of the Codex and documentation more generally?

This group are using the Codex as a reference, particularly the function reference and hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.. While some of them are confident enough to look in the source code, they still rely heavily on the Codex references.

If they can’t find what they need they often look to stack exchange and other support forums for their answers.

For learning new skills, they are particularly interested in written tutorials. A small subset is interested in Screencasts.

Based on your review of the survey, what recommendations would you make specifically about the WordPress CodexWordPress Codex Living online manual to WordPress.org https://codex.wordpress.org/ that would help these users?
- ensure that there is adequate information to show them how to use new WordPress features – e.g. the 3.5 media uploader
- ensure that every function, class and hook is documented, with adequate explanations and examples
- separate of user and developer content to enhance experience for users and devs
Based on your review of this survey, make three recommendations for improved documentation that would serve these users:
- Better code reference including docs for all functions, hooks, and classes. These should include adequate examples and explanations.
- theme and plugin developer handbooks to teach people about specific aspects of development
- better search functionality
Some more
- an article (or links) repository on developing with different WordPress features
- canonical plugin and theme templates that have code that can be copy and pasted to state a plugin and theme. The template should encourage good code structure and minimize global namespace pollution
- a list of recently updated pages
- better translation tools
Contributing to WordPress Docs

What percentage of these users have contributed to WordPress Docs?
23%

What percentage are aware that they can use their WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ login to edit the Codex?

51%

What percentage would like to contribute to WordPress?

77%

How can we make it easier for these users to contribute to WordPress docs?
- a list of areas that need help
- clearer documentation on how to get started
- don’t use mediawiki
- make it clearer that anyone can edit the Codex (maybe an “Edit this Page” link at the top of every page)
- documentation templates that can be used for creating new docs
- create a short GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/-style markdown reference
- gamification, rankings, profiles
I liked this answer:
I find opening up a Wiki page and editing a bit intimiating. My confidence just isn’t there. In contrast, heloping people on the forums is really fun and rewarding. Perhaps there can be some way to transition material from the forums to the codex? Like a multi-step process? I’m imagining…
- When someone helpfully answers your question in the forums, flag it as “this answered by question”
- Then have an interface where all posts so-tagged can be reviewed by editors (anyone, really), and nominated for inclusion in the codex
- And then a final step where someone actually adds the example to the codex page
I don’t know.

But my point is that the Forums are easy and approachable, while the codex seems intimidating.
Also:

One thing that would be neat is a little more recognition for docs contributors. I realize it’s a little bit egotistical, and I know you can see a history of edits to a page, but it would be cool if there was some sort of official recognition, even if only for people who have contributed a certain amount. Contributing code gets you very public “props”, and documentation is sometimes just as important. Not a big deal though.

Another good idea

Assign someone to hunt for good tutorials and content on the internet, contact the authors and see if they will contribute it to the Codex
Drew Jaynes (DrewAPicture) 8:17 pm on June 13, 2013
User Type: Advanced

Learning preferences:
- 29% – Written Tutorials
- 24% – Breaking stuff and putting it back together
- 21% – User guides
- 8% – Screencasts and video tutorials
- 6% – Books
- 5% – Asking questions in the support forums
- 4% – Other
- 3% – In-person training
Notable answers listed under other:
- Several mentions of ‘examples like jQuery/php.net’ see: Code reference
- Reading the source code
Top three places to look for an answer to a question:
1. 34% – Google / other search engines
2. 30% – Official documentation
3. 17% – 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
Other places these users look regularly for answers:
- Overwhelmingly StackOverflow/StackExchange
Usefulness of the Codex to the Advanced group:

79% of respondents give the Codex 7/10 or higher in terms of usefulness
1. 22.1% – 9/10
2. 21.8% – 8/10
3. 18.4% – 7/10
Most useful sections of the Codex:
1. 39% – Function Reference
2. 22% – PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party Development docs
3. 19% – Theme Development docs
The main problems these users face with the Codex:
1. 33% – Incomplete documentation
2. 20% – Out of date documentation
3. 13% – Difficulty navigating
Documentation these user would like to see more of:
1. 47% – Better code reference
2. 23% – Written tutorials
3. 15% – Handbooks focused on specific tasks
General observations:
- Advanced users seem to be using the Codex quite a lot, which makes its incompleteness from a Function/Class/HooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. reference all the more obvious.
Codex Recommendations:
- Easily the best thing we can do is get the Function/Class reference out of the Codex and into the Code Reference. As long as we stay vigilant with providing accurate PHPDocs in the code, the parser would do probably 70 percent of the work
- A better organized (and complete) hooks reference would be a bonus, though they are not documented much if at all in-code like functions and classes are.
Documentation Recommendations:
1. When referencing examples in the Codex (or the Code Reference), mark examples based on difficulty, e.g. easy, intermediate, advanced.
2. Provide better navigation (linking) between functions that use each other or are in so other way related.
3. Make related (but separate) docs more accessible, such as the handbooks.
Contributing to WordPress Docs:
- 33% of advanced users have contributed to the Codex
- 57% are aware they can edit the Codex
- 78% would like to contribute
Top three ways we can make it easier for these users to contribute:
1. Pay them or force them not to be lazy (their words, not mine)
2. Make it more apparent what needs to be done and how to do it
3. Add @link tags in the PHPDocs to relevant Codex/Code Reference pages
Also here: https://docs.google.com/document/d/1GHU-dX45BcqkwRlsygcwRN0jFrOaVVwTWjwWL9rylgo/edit?usp=sharing
Jerry Bates (JerrySarcastic) 5:53 am on June 14, 2013
User Type: WordPress user

“I use WordPress to run my website/blog”

Learning preferences:
- Written Tutorials – 29%
- User Guides – 25%
- Screencasts and video tutorials – 17%
- Asking questions on support forums – 9%
- Books – 7%
- Breaking stuff and putting it back together – 6%
- In-person training – 5%
- Other – 2%
Note: Nothing terribly useful under “other” for this question.

Top three places to look for an answer to a question:
- Google – 39%
- Support Forums – 29%
- Official documentation – 19%
Are there any other places that these users are regularly looking for answers?
- Inline Documentation
- YouTube
- Local developer
- “There is really no place to find information that helps for someone who is new to the WHOLE process.”
How useful is the Codex to this user group?
6/10 – So for this group the usefulness of the codex is below average.
(answers 134 sum 866 mean 6)

What sections of the Codex do these users find most useful?
- WordPress Lessons – 22%
- User Guides – 18%
- FAQs – 14%
What are the main problems these users face with the Codex?
- I can’t find what I need – 25%
- Incomplete Documentation – 17%
- Content isn’t clear – 16%
What documentation would these users like to see more of?
- Written Tutorials – 28%
- Handbooks focused on specific tasks – 22%
- Better Help in the WordPress Dashboard – *17%
- Screencasts – *17%
* results are tied

Based on your review of this survey, do you have any general observations about how this user group is making use of the Codex and documentation more generally?
Not surprisingly, the codex is seen as a bit overwhelming for non-technical users. While some sections Codex (such as lessons and user guides) are useful, but judging by the fill-in responses, for the most part the codex is not particularly helpful for this group of end users. Some feedback:
- “Sometimes, the very simple questions are not answered”
- “My main problem with the documentation is that it doesn’t hang together. Wherever I land in the Codex, I feel like I’m missing something”
- “The amount of text is overwhelming for beginners…”
- “I don’t find it helpful at all. I go to the Codex as a last resort”
Based on your review of the survey, what recommendations would you make specifically about the WordPress CodexWordPress Codex Living online manual to WordPress.org https://codex.wordpress.org/ that would help these users?
As we have discussed the likely home for this group is learn.wordpress.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/, and not the Codex, but respondents to this survey are very clear about improvements in three major areas:
- Content – More tutorials, step-by-step style lesson plans, videos screencasts, and more (and better)screenshots of key elements. Also more examples of WordPress in practical use, and examples with “How to” explanation would be appreciated.
- Navigation – Users feel pretty lost in the Codex as-is, so clearer and more intuitive navigation (as well as a more thought out organization overall) would make the Codex more helpful for this group. I think this also speaks to the need for better lesson plans and pathways for learning.
- Discoverability/Search – Related to the above problem, users would be much better served by having clearer access to content, especially the ability to search for relevant information, and one request to have information in the dashboard, where it is needed most.
Based on your review of this survey, make three recommendations for improved documentation that would serve these users:
1. Clear, step-by-step tutorials for the most basic WordPress tasks and concepts
2. Video and text side-by-side, as well as generous use of screenshots
3. Simplified navigation and a separation from technical or developer resources
Contributing to WordPress Docs – Users

What percentage of these users have contributed to WordPress Docs?
22%

What percentage are aware that they can use their WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ login to edit the Codex?
30%

What percentage would like to contribute?
60%

How can we make it easier for these users to contribute to WordPress docs?
Most respondents said that they felt they were not experienced enough in WordPress to feel ready to contribute at this time. However, a few responses stood out:
- “I’d like to see a user guide specifically for editing the Codex. I think editing the Codex is intimidating and people are afraid they’ll break something.”
- “I’m do not know enough YET to make knowledgeable contributions. But having an “edit” visible on the page I’m viewing would be helpful. And in a tip or pop-up with the edit, explain what I could do, etc.”

Want to get involved?

Weekly meetings

The Codex survey is closed and the next…

Outline for Report

Contributing to WordPress Docs

Want to get involved?

Weekly meetings

Outline for Report

Contributing to WordPress Docs

Share this: