Ian Dunn 3:45 pm on July 8, 2015
Tags: documentation ( 9 ), Improving WordCamp.org ( 17 ), official websites ( 44 ), wordcamp.org ( 34 )

Better WordCamp.org Docs

One of the projects we identified to improve WordCamp.org 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 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/ 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 plan.wordcamp.org, along with some videos, but there are many ways that it falls short.

Problems

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 WordCamp.org 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 “WordCamp.org 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 WordPress.org Plugin Directory https://wordpress.org/plugins/ 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 https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. 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

Drew Jaynes 3:58 pm on July 8, 2015

I think putting content into a help tabs solution in wp-admin would be a good way to centralize it. Or even some kind of help mechanism tied to specific screens that pulls in from somewhere.

The “pulls in from somewhere” part I think could be handled at the network level which could feasibly allow editing documentation within the WordPress UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. instead of forcing the need for patches (like with help tabs). For that matter, we could also bring it in from the Plan site via JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. or something into a container on targeted pages.

The downside of bringing it into wp-admin is that there isn’t a great opportunity to make it searchable. Often times, I knew there was documentation somewhere on the planning site because I’d read it before but I couldn’t remember where. That might be eased quite a bit by introducing context but it’s a point worth considering.
- Ian Dunn 6:00 pm on July 8, 2015
  
  Making sure things stay searchable is a great point to bring up. I’m guessing we’ll still want some way to browse all of the documentation in one place, the way you currently can, so hopefully we could set the Contextual Help tab up in such a way that it pulls from the browsable content, or vice-versa.
  
  The content itself will live in regular pages, so that shouldn’t be hard. The only potential problem I see is that they’re intended for two different contexts, so we may not want to show the exact same thing in both places. The Contextual Help tabs should probably be as brief as possible, while the browsable content should have screenshots and more detailed explanations.
  
  I’m not sure what you meant about introducing context, though; could you elaborate on that?
Ian Dunn 5:45 pm on July 8, 2015

Forgot to pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” @dimitris33 above; Jen said you might be interested in this project.
Morgan Kay 6:14 pm on July 8, 2015

As we all know, people never read documentation. I think there needs to be as much contextual documentation as possible. To keep the documentation centralized and maintainable, maybe there should be contextual links to external resources – that way we could put all the documentation in one place, but make sure people can find the exact documentation they need right when they need it.

Could we work some very brief training into the organizer on-boarding process? It would only take a few minutes during a budget review to say, “hey, now that your budget approved and your website is up, here’s a quick overview of how to use the website and here’s a link to more detailed documentation.”
- Ian Dunn 11:19 pm on July 8, 2015
  
  Linking to the offsite documentation would definitely be a much simpler solution than trying to manage things in two places — even if that were aided by some code — but I wonder if people would be turned off by having to open an external page, rather than having it right there in front of them?
  
  Now that I’ve written that down, though, that does sound kind of silly. It’s not like clicking an extra link is a lot of work. At the very least, that might be a great v1.
  
  Bringing the website up during orientation is a great idea. IIRC, @jenmylo was recently talking about adding more training for all of the specific roles on organizing teams, including the website devs/designers/content managers, so I think there are already some plans for that in the works?
sethmatics 6:41 pm on July 9, 2015

As a prior 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. organizer, the issue I had is certainly my perception of how we were able to run WordCamps in the past versus the new limitations and requirements of the WordCamp websites and tools. I’m thinking documentation might look a little different for new WordCamp organizers then it would for WordCamp veterans.

Unfortunately, without custom plugins or themes the “open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL.” feel of WordPress feels very “closed source” when you become a WordCamp organizer. It certainly does not exemplify to our target audiences the full potential of WordPress, which is probably why we “fight against the grain” to get something more custom for our events.
- Ian Dunn 7:33 pm on July 9, 2015
  
  Hey Seth, there’s a discussion dedicated entirely to that if you’d like to give feedback on the challenges and potential solutions.
  
  As far as docs go, do you have any thoughts on what would have helped you when you were returning, or any of the ideas above?
  - sethmatics 12:47 am on July 10, 2015
    
    I would assume you guys have a better handle on an FAQ for previous organizers then me, but questions that were hot topics for us were:
    1. how communication can be handled?
    in the past we organized our own lists and communication usually in smart systems that can automatically drip appropriate content based on information we know about each person. the new rules don’t really allow for this type of communication, so you can’t run the same kind of event.
    2. how much control do the organizers really have over the event?
    in past years we have far more control over how, when, where the events happened. now it seems to be very regulated and “only on approval”. all sorts of red tape to deal with now, making these events challenging to run, and really far less enjoyable to try to organize.
    3. How can we get sponsorships?
    this is a big one, because when people try to support large communities for WordCamps, like Phoenix, we want to support as many people in the community as possible. If 1,000 people want to come, I want to have space for 1,000 people. realistically though, with the way sponsorships are sold, it’s hard to find local businesses to support the WordCamps when they really get little to nothing in return. It requires money to run an event, and more money to run a big event. any information about acceptable ways of properly getting sponsorships would greatly help new organizers I would think.
    4. who to contact and what to expect when organizers have questions?
    again, in the past its typically been very challenging to get timely responses, and sometimes answers to our questions would change. Can we do X, first yes, then no. setting up proper expectations for organizers of how long responses may take to get, would likely reduce any anxiety on this topic.
    
    In all honesty, it also feels like WordPress FoundationWordPress Foundation The WordPress Foundation is a charitable organization founded by Matt Mullenweg to further the mission of the WordPress open source project: to democratize publishing through Open Source, GPL software. Find more on wordpressfoundation.org. is trying to dictate the size of the WordCamps. All these rules and regulations makes the process, as I said, feel very “Closed Source”, which I just don’t think is the right way to approach WordCamps. At this point I’ve simply removed myself from any of the organizing, and only offer up my time and skills to actually helping on “day of” activities. It saddens me to do that, as I truly consider myself a WordPress Evangelist before a WordPress developer. I’m just waiting for the day when 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. organizing is back to a creative project with the same open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. feel the product delivers. Until then I’ll just wait quietly on the sidelines.
    - Ian Dunn 4:02 pm on July 10, 2015
      
      Thanks for the detailed feedback Seth 🙂
      
      You concerns are definitely valid, but this project is focusing on documentation for the tools on WordCamp.org, rather than the entire organizing process, so most of them are better addressed by the deputiesProgram Supporter Community Program Supporters (formerly Deputies) are a team of people worldwide who review WordCamp and Meetup applications, interview lead organizers, and keep things moving at WordCamp Central. Find more about program supporters in our Program Supporter Handbook. who help onboard and mentorEvent Supporter Event Supporter (formerly Mentor) is someone who has already organised a WordCamp and has time to meet with their assigned mentee every 2 weeks, they talk over where they should be in their timeline, help them to identify their issues, and also identify solutions for their issues. organizing teams.
      
      CC’ing them so they can learn from it — @karenalma, @camikaos, @andreamiddleton, @brandondove, @adityakane, @jenmylo, @chanthaboune, @kcristiano
      
      The communication aspect is definitely relevant to this discussion, though. In the past year we’ve added integration between CampTix and MailChimp — which IIRC, Phoenix used for their 2014 camp — and we also created a way for CampTix to natively send e-mails to targeted segments of the attendee base (e.g., those who stated dietary restrictions, ordered a certain type of t-shirt, etc).
      
      I don’t think we’ve done a good of documenting those, though, and it’s probably affected by all 4 of the things mentioned in the Problems section above. That’s the kind of thing that this project is trying to solve, so hopefully it will be addressed by the ideas in the “Brainstorming Solutions” section. If you have any feedback on those ideas, I’d love to hear it 🙂
Josepha 10:15 pm on July 10, 2015

I like the idea of videos as an alternative, but I worry about possible difficulties in locating exact pieces of information quickly. Making it the primary source of information probably isn’t the best idea.

The demo site seems like it would be worth exploring and I am always in favor of contextual help if it doesn’t end up being cluttered (as you mentioned).
Ian Dunn 3:47 pm on September 21, 2015

WP Help might be useful for this project.
Ian Dunn 12:19 am on May 28, 2016

We’re always adding new features […] there isn’t a good way for returning organizers to know what’s changed since […] last year.

Wufoo does something interesting there with their “Since You’ve Been Gone” feature.

We probably wouldn’t want to implement it the same way they did, but it’s good fodder for brainstorming.

Welcome!

Get Involved

Let’s Talk

Learn More

Better WordCamp.org Docs

Problems

Brainstorming Solutions

Welcome!

Get Involved

Let’s Talk

Learn More

Problems

Brainstorming Solutions

Share this: