WordPress.org

Ready to get started?Download WordPress

Make WordPress Documentation

Welcome to the official blog for the WordPress documentation team.

This team is responsible for all things documentation, including the Codex, handbooks, developer.wordpress.org, admin help, inline docs, and other general wordsmithing across the WordPress project.

Want to get involved?

Join the discussion here on the blog, or check out the landing pages for:

Weekly Meetings

As well as discussing docs issues here on the blog, we use IRC for group communication.

Our regular meeting is on Thursdays at 23:00 UTC in #wordpress-sfd IRC on Freenode.

Individual teams have their own regular meetings, you can find details of those in the sidebar.

Recent Updates Toggle Comment Threads | Keyboard Shortcuts

  • trishasalas 3:56 am on April 11, 2014 Permalink
    Tags:   

    Admin Help Update for Week of 4/7/2014 

    We’ve had a quiet few weeks as I was busy building a resume, interviewing and rounding up code.  But yay for new jobs and time to move forward!

    Thanks to @clorith and @jazzs3quence for picking up the slack! I’ve talked to @designsimply and we are going to start user testing asap.  In the meantime we can continue to watch the older usertesting.com videos and I would love to see some write ups like @jazzs3quence recommended. :)

    Thanks for the patience everyone, back to weekly updates from here.

     

  • Siobhan 11:32 pm on April 10, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Need a volunteer to help prepare for Codex updates 

    WordPress 3.9 is arriving next week, which means that we need to get the codex updated. It helps to have a master list of pages in the codex that need to be updated, like this one here. We’re looking for a volunteer (or volunteers) to compile this list.This involves:

    1. Listing all of the new features, functions, etc in a P2 post. The 3.9 Codex page has many of them.
    2. Finding all of the pages in the Codex that need to be updated to reflect the changes in WordPress and listing them. (You can create a checklist by putting a o at the start of a link in P2.)

    This helps a lot with keeping track of what’s done and what needs to be done.

    Anyone interested?

     

  • Kim Parsell 3:01 am on April 5, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Docs Chat: Apr. 3, 2014 

    Thank you to everyone who came. For anyone unable to attend, you can read the logs here.

    The following is a summary of the topics that were discussed.

    1. DevHub: Work continues on the parser, and has resumed on the code reference theme.

    2. Admin Help: @Clorith said the team is still reviewing existing user tests to identify pain points in admin areas that haven’t been updated since the original tests were conducted.

    3. Handbooks: @blobaugh is currently reviewing the existing content in the Plugin Developer Handbook. He also plans to review content in the Codex to see what can be moved over to the handbook. @sewmyheadon wasn’t able to attend the chat, but sent a reminder about this weekend’s Seattle Docs Meetup – Saturday, April 5th at 10am PDT. You can also attend virtually in the #wordpress-sfd IRC channel.

    4. Docs Conferences: The list of talks was announced Thursday for Write The Docs NA. Both @siobhan and @DrewAPicture will be speaking – “Writing For Your Other Half” and “Putting the (docs) Cart Before the (standards) Horse“.

    5. Miscellaneous:

    • IRC Chat Times: Please review the listing for your group’s weekly IRC chat to be sure the times are correct. I pulled info from IRC logs and posts on make/docs to make the corrections for the DST changes.

    • Handbooks Master List: @DrewAPicture asked whether there should be a master list of all the handbooks (core/plugin dev/theme dev/team-specific) and who the point of contact for each is. If so, where should that live? The handbooks the Docs team is responsible for are listed in our handbook. It was suggested we could include a list of handbooks available on other Make sites in our handbook, with a link to each handbook and a point of contact.

     

    • samuelsidler 5:37 pm on April 5, 2014 Permalink | Log in to Reply

      As I mentioned in the chat, we need a central place to list all handbooks (developer and contributor) in progress or fully created. I’m not sure that belongs on the make.wordpress.org front page. While the docs team isn’t responsible for all the handbooks, it could still create the list of handbooks. As of now, the only two that are missing from the list are mobile and polyglots.

      • Kim Parsell 8:26 pm on April 5, 2014 Permalink | Log in to Reply

        I agree, they don’t need to be listed on the front page of make.wordpress.org. Support also has a handbook that they are responsible for maintaining, so currently we have 5 team handbooks plus theme/plugin developer handbooks.

  • Drew Jaynes (DrewAPicture) 10:47 pm on March 31, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Looking for a volunteer to add a “Stopwords” section to Translating WordPress > Types of Messages in the Codex.

    Relevant information can be found in the ticket description for #26670.

     

  • Kim Parsell 7:31 pm on March 30, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Docs Chat: Mar. 27, 2014 

    Thank you to everyone who came. For anyone unable to attend, you can read the logs here.

    The following is a summary of the topics that were discussed.

    1. DevHub: @siobhan said there are two issues left to address with the parser. Once that is finished, attention turns to completing the handbook and code reference themes. (3/25/2014 team meeting summary)

    2. Admin Help: @jazzs3quence said they are looking back at the original user testing videos, and prepping for new user tests. They have received some good feedback on the list of admin tasks. Starting this week, the weekly meeting on Mondays will be held at 17:30 UTC.

    3. Handbooks: @blobaugh said he received an email from @jdgrimes, offering to donate some tutorials on unit testing for the Plugin Developer Handbook. @sewmyheadon said there is nothing new to report on the Theme Developer Handbook. He said the next Docs Meetup in Seattle is April 5th, and hopes for another good turnout to work on both handbooks. You can attend in person in Seattle, or remotely in the #wordpress-sfd IRC channel.

    4. Codex Updates for 3.9: The Codex will need to be updated after 3.9 is released. @siobhan suggested we go back to doing a virtual sprint for the updates. We can build the task list for the sprint from the 3.9 version page that @DrewAPicture is working on.

    5. Upcoming Docs Conferences: I posted earlier this week about upcoming docs conferences. @siobhan will be speaking at Write The Docs in Portland in May. I’ll be attending the OpenHelp conference in Cincinnati in June. OpenHelp contacted @siobhan about whether we plan to send a team and/or sponsor this year’s conference in Cincinnati.

    6. Docs Chat Time Change: Starting this week, the meeting time will shift to 23:00 UTC on Thursday to get us back to our old schedule – 4pm PDT, 5pm MDT, 7pm EDT, 12am London (Friday).

     

  • Siobhan 8:29 pm on March 25, 2014 Permalink | Log in to leave a Comment
    Tags:   

    devhub update 

    Long meeting today in devhub land! Here’s what was discussion:

    • WP-Parser: methods need to be broken up into CPTs
    • WP-Parser: amendments need to be made to how inline docs are parsed into the_content
    • we discussed editing of content in the code reference in the WordPress Admin. We agreed that only admins should be able to edit the content and only in extenuating circumstances. @siobhan to open the following tickets:
      • that the_content be locked for code reference post types to admins only 411
      • that an internal flag system be added so that we can keep track of things that have been edited (with a view to the docs team ensuring that all inline docs patches are updated prior to a WP update 412
    • we agreed that the theme and plugin dev handbooks should stay as CPTs, and that @nlarnold1 is free to do as she chooses with the handbook plugin
    • I made a list of proposed templates for the theme, but @nlarold1 has been using template parts and gave me an excellent lesson on how they work. Nicole to edit and update the google doc
    • We discussed changing the prefix for the CPTs generated by WP-Parser. Currently it’s wpapi which will potentially be used by a feature plugin and it would be nice to keep them separate.
     

  • Kim Parsell 11:02 pm on March 24, 2014 Permalink | Log in to leave a Comment
    Tags: conferences   

    Upcoming Docs Conferences 

    There are three documentation conferences coming up in the first half of 2014:

    1. March 31-April 1, 2014: Write The Docs-EU, Budapest, Hungary

    This is the first year for Write The Docs-EU. I know it’s short notice, but it appears that tickets are still available if you can make it there.

    2. May 5-6, 2014: Write The Docs-NA, Portland, Oregon

    This is the second year for the Write The Docs conference in Portland.

    3. June 14-18, 2014: OpenHelp Conference, Cincinnati, Ohio
    (conference: June 14-15; documentation sprints: June 16-18)

    This is the fourth year for the OpenHelp conference.

    OpenHelp 2013 was the venue for the first WordPress Docs Team Summit.

    WordPress is sponsoring both Write The Docs conferences this year, and was a sponsor for the OpenHelp conference in 2013.

    The conferences are great opportunities for anyone who writes documentation, whether it’s for an open-source project, or providing user or technical documentation for themes, plugins, hosted services, etc.

     

  • Kim Parsell 4:43 pm on March 23, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Docs Chat: Mar. 20, 2014 

    Thank you to everyone who came. For anyone unable to attend, you can read the logs here.

    The following is a summary of the topics that were discussed.

    1. DevHub: Work continues on fixing parser-related issues. @siobhan posted on Make/Core, looking for volunteers to help with the parser and the handbook theme. If you would like to work on the project, leave a comment on the Make/Core post, or come to the weekly IRC chat on Tuesdays at 19:00 UTC.

    2. Admin Help: @trishasalas said the group’s current focus is on discovering what problems users are currently having, and addressing those with appropriate solutions. @designsimply has agreed to help with user testing. The team will start with a few simple tests, and see what those reveal. They are compiling a list of tasks to be used during testing. If you would like to be part of the effort, please attend the weekly meeting on Mondays at 18:30 UTC. (3/17/2014 team meeting summary)

    3. Handbooks: I asked @samuelsidler when the Theme Developer and Plugin Developer handbooks would be moved over to DevHub. He said he wasn’t sure, but there are some encoding issues that may require them to be moved manually. @siobhan said it was important to retain the contributor information to be used on the Credits page for each handbook.

    4. WordPress Core Style Guide: Fred Clay Meyer and @joshlevinson attended the meeting to discuss their proposal for a WordPress Core Style Guide. Discussion centered around how they could best present their ideas to the core team to begin the discussion. The team suggested that Fred put together a proposal to present at a core dev chat after 3.9 is released.

     

  • trishasalas 7:52 am on March 19, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Admin Help User Task List 

    WordPress User ‘Tasks’

    We are gathering a list of things (tasks) any user might do in the course of setting up a WordPress site.

    We need your help to add to this list!!

    Please feel free to add your ideas in the comments.

    • Upload and configure WordPress
    • Remove the default post and comment
    • Drop by the theme editor and find the right theme
    • Writing my first post
    • Make the site “yours”
    • Create some content
    • Create a new front page
    • Remove the default admin account or restrict its permissions
    • Add new user(s)/admin(s)
    • Setup Akismet
    • Search for and install a plugin
    • Setup pretty permalinks
    • Change the default tagline from “Just another WordPress blog”

    You can read more about the purpose for this list here.

     

    • Daryl L. L. Houston (dllh) 12:08 pm on March 19, 2014 Permalink | Log in to Reply

      Some possible ideas at http://learn.wordpress.com/ (it’s wpcom material but much of it would transfer to .org).

    • Chris Reynolds 3:13 pm on March 19, 2014 Permalink | Log in to Reply

      Activate multisite! (muahahahahaha)

    • ShayHurley 5:05 pm on March 19, 2014 Permalink | Log in to Reply

      • Remove the default admin account or restrict its permissions
      • Add new user(s)/admin(s)
      • Setup Akismet

    • Chris Reynolds 5:32 pm on March 19, 2014 Permalink | Log in to Reply

      • Search for and install a plugin
      • Setup pretty permalinks
      • Change the default tagline from “Just another WordPress blog”

    • trishasalas 7:16 pm on March 19, 2014 Permalink | Log in to Reply

      ….are you trying to scare people off, @jazzs3quence? ;)

      (activate, multisite…that’s funny)

      • Chris Reynolds 7:20 pm on March 19, 2014 Permalink | Log in to Reply

        I think it’s worth thinking about. Activating and setting up multisite is under-documented and tricky. Mastering that, or having some system in place that walks you through the process without having to look it up on the Codex would be *amazing*.

    • trishasalas 7:23 pm on March 19, 2014 Permalink | Log in to Reply

      Actually, I completely agree but it brings up the point again about funneling. Some will need to do this and some will never even think of it. I think we need to think about the testing in terms of groups. Maybe the User Capabilities would be a good place to start.

      I was going to comment something similar on @shayHurley‘s comment as much of what he suggested would not be applicable to the average user. (but that brings up another question, who is our average user?)

      • Kim Parsell 10:45 am on March 22, 2014 Permalink | Log in to Reply

        Rather than have them remove the default admin account, it would be better to have them create a new user account and assign a role to it. This account could be for a friend who will also be writing on the blog, but probably shouldn’t be an admin. What role should be assigned to them (i.e., level of trust)?

    • joshlevinson 2:23 pm on March 21, 2014 Permalink | Log in to Reply

      I’d like to open a bit of discussion on the importance of

      • Remove the default admin account or restrict its permissions
      • Add new user(s)/admin(s) (as a necessary result of doing the above step)

      In my opinion this is not only unnecessary, it degrades the perceived quality of WordPress. Recommending users to delete the first user and recreate it as part of setting up a WordPress site would make one wonder, “Why didn’t setup do something like this for me?”
      It would make one feel less confident in the default security of WordPress.

      To my knowledge, the only security concern with having a user ID of 1 (which I assume is the concern that the recommended steps are intended to assuage) is one that is experienced if an attacker has already gained some way of modifying or reading directly from a site’s database. This would signify a problem further up the chain. Perhaps a more useful fix would be to prevent users from setting up a WordPress site with the “low-hanging fruit” usernames (admin, Admin, administrator, etc.).

      I vote to have those item removed from the task list – consider that users don’t always look for help when they need help doing something, they often look at a task list simply because it exists.

      • Josh Levinson 2:44 pm on March 21, 2014 Permalink | Log in to Reply

        I read a little more into this topic, and found out about WordPress’s “user enumeration vulnerability”. This basically makes the steps to remove the default account (and blocking easy-to-guess usernames) even less useful, as enumeration could be used to determine usernames no matter what the IDs are. This only reinforces the importance of enforcing strong passwords.

      • Trifon 12:12 pm on March 23, 2014 Permalink | Log in to Reply

        Ever since the admin account can be named in the install process, deleting the default account really has become a useless step.
        Choosing a strong passwords and a different name for the default account really should be enough.

    • Bradley Allen 5:32 pm on March 22, 2014 Permalink | Log in to Reply

      Adjust widgets

    • Trifon 9:56 pm on March 25, 2014 Permalink | Log in to Reply

      • Adjust timezone
      • Adjust date/time format

  • trishasalas 7:50 am on March 19, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Admin Help Updates from 3/17/2014 Meeting 

    Thanks so much to everyone who attended this week.  If you were unable to make it to the meeting feel free to read the logs.  This weeks meeting was quite a bit more low-key.  We had fewer in attendance possibly due to the holiday and/or the time change.

    The first few minutes we discussed meeting times and have decided to keep the meeting at 18:30 UTC until Europe changes time April 1.  We will meet at 17:30 UTC beginning with our April 7th meeting.

    I would like to reiterate that this is almost a completely new direction from where this group started.  Our original goal was to make the existing Admin Help content more visible to users.  The goal now is to create a user experience that is more intuitive by discovering what problems users are currently having and addressing those with appropriate solutions.

    Sheri Bigelow (@designsimply) has agreed to help with user testing ♥.  We are going to start with a few simple tests and see what that reveals.  We can use the information from that testing to move forward with additional tests.

    @kpdesign created a Project Page for us, we’ll use that to link to external resources as well as any additional project pages that we need.  You can find that page here http://make.wordpress.org/docs/handbook/projects/admin-help/

    What we need: People who love UX/UI and want to see new users succeed with WordPress.  Practical needs are people to help identify tasks, create storyboards, personas, user testing evaluation and any other tasks that might be relevant at this early stage.

    We also need tasks added to our ‘User Task List’.  You can find the list here and read more about it here.

    We will send out a call for developers when we know what kind of developing we need ;)

    Join us on Mondays at 18:30 UTC in the WordPress-sfd IRC channel.

     

← Older posts

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel