Better Docs

One of the projects we identified to improve was to have better documentation.

Sometimes organizers aren’t aware of the intended approach to building a WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. site, or of the tools that are available, so they end up doing things the hard way, or in a way creates a worse experience for participants.

For example, if an organizer doesn’t make use of the custom post typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. for speakers, then those speakers won’t get a badge on their 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. profile, and the upcoming Android app won’t be able to display speakers for that camp.

We do have a lot of written documentation on, along with some videos, but there are many ways that it falls short.



Here are a few of the problems we’ve already discussed, but please leave comments with any others that you see.

  • There’s a lot of documentation, and most people won’t read through everything.
  • Organizers have to visit an external site to reference things while working on their WordCamp site.
  • We’re always adding new features and iterating on old ones, but there isn’t a good way for returning organizers to know what’s changed since they used the site last year.
  • Building a site on is different than what most organizers expect, so they need to shift their mindset in order to not fight against the grain. For example, organizers can’t upload custom plugins or create child themes; the majority of customization is done with CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. and our custom tools.

Brainstorming Solutions

Here are a few ideas, but please add more in the comments, and leave your feedback on these.

  • Bring documentation into wp-admin, in the form on Contextual Help and Admin Pointers.
    • Should we bring all documentation into wp-admin, or just certain types (like cheat sheets)? If everything is in wp-admin, it will be hard to get an overview. Maybe a hybrid approach?
    • We should probably create a new “ Help” contextual tab rather than integrating into CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s generic “Help” tab, because that would be more discoverable and less cluttered.
    • Duplicating documentation in multiple places would be harder to maintain, and they’d likely get out of sync.
    • Hard-coding documentation into a 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 Plugin Directory or can be cost-based plugin from a third-party (rather than the current WordPress pages) would make it impossible for non-developers to update and improve the documentation, which would be a bottleneck. Maybe we should build a way to programmatically import documentation from Plan into wp-admin? It might need to be pages specifically crafted for wp-admin screens, though, rather than the kind of lengthy articles we have now.
  • Add more videos, because sometimes those are easier to digest than long articles.
    • Are there specific types of content that are better for video than others?
    • Would this have a negative impact on non-English speakers?
  • Encourage organizers to ask questions in #events on SlackSlack Slack is a Collaborative Group Chat Platform The WordPress community has its own Slack Channel at when they don’t know something, and when they’re not sure if there’s a better way to do something?
  • Create an demo site that is “perfect”, and then make a video walking through it, showing the best way to set things up.
    • We could also give organizers read-only access to it, so they could explore and play around.
  • Make the system more intuitive, so that formal documentation is less necessary.
    • For example, we currently pre-populate new sites with default pages to provide examples of common content and shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site. usage.
    • What other things could we do?
  • Create a page that has an index of all the significant changes since their last camp. Organizers could visit the page and enter a date range, then get a short description of all the changes, with links to their full documentation.
    • One downside to this it would require extra time from developers, each time they make a change, and we already have limited time. It might be possible for volunteers to do a lot of it, but it’d still require extra developer time to inform the volunteers about it and give them all of the information they’d need to document it.
    • Another idea would be a mailing list where a message gets sent out each time something new is released. A big downside to that, though, would be that organizers would probably forget most of the info by the time their next camp rolls around.
    • Another idea would be to create a video once a quarter that walks through all the changes in the past three months. This has the same drawback as the original idea, but it might be a better format, and doing it once a quarter might be easier doing it than every time a change happens.

What are you thoughts on all of that? What other problems and solutions do you see?


Everyone is encouraged to participate in the discussion, but I’m pinging the people who took part in the previous discussions to make sure they don’t miss the post: @ryelle, @harbormark, @chanthaboune, @nvwd, @kovshenin, @rafaehlers, @davidjlaietta, @dimensionmedia, @iandstewart, @miss_jwo, @topher1kenobe, @jenmylo, @georgestephanis, @valeriosza, @jb510, @jleuze, @robertnienhuis, @cheffheid, @dnelle, @danielgcarvalho@brettshumaker

#documentation, #improving-wordcamp-org, #official-websites, #wordcamp-org