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.

The team holds weekly office hours on Thursdays from 17:00-18: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

  • Siobhan 8:06 pm on August 26, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Devhub Update August 26th 

    Thanks everyone who came to the meeting! Here’s what we discussed:

    Parser

    • @Rarst has committed some pull requests. 124, 123, 122, 121
    • @siobhan to go through WP-Parser issues and mark any that need to be worked on for devhub

    Code Reference

    Handbook Theme

    • @sams to report back on content migration and report any issues with the theme that appear during migration.

    Note: if anyone is making any major changes please open a ticket on trac to go with the change.

     
  • Siobhan 7:10 pm on August 21, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Devhub Update 21st August 

    Thanks everyone who came to the meeting on Tuesday. It was an extra-long meeting because we did a bug scrub. Here’s what he discussed:

    Tickets

    • #449 The parser doesn’t yet detect deprecated functions so we can’t move on this. We should have a similar notice for pluggable functions.
    • #197 – closed. Markdown is not being parsed in parameter docs. I’ve opened a ticket on Github for that.
    • #492 – this is an issue with inline docs not being escaped. @DrewAPicture is to figure out what is the best method for escaping markdown, update the handbook, and see that the inline docs are properly escaped.
    • #182 This is wider issue for wp.org and should be worked on by the meta team.
    • #252 ryelle created a page template for dashicons. We’ll need a new ticket when we need a fuller resources page.
    • 411, 481, & 180 – changes should be landed this week (per @coffee2code & @DrewAPicture)
    • 542 – blessed. @nicolealleyinteractive is investigating

    Anything else

    • Changes to examples/curated content & explanations should be landed this week
    • Handbook theme is progressing. We’ll discuss it in more detail next week.

    Parser issues

    The bug scrub emphasised how much we need a new maintainer for the parser. @Rarst has done a great job but in his absence we need someone to keep it moving forward. The following tickets are pending work on the parser:

    Until there’s some work done on the parser none of these tickets can be worked on. If anyone is interested in volunteering please let me know.

    What are you working on?

    If you’re actively working on devhub, can you please leave a comment on this post with a list of things that you’re working on in order of priority. I want to make sure that everything has a ticket. It will also help me get a better handle on where we need to get more volunteers.

     
    • Andrey "Rarst" Savchenko 7:17 pm on August 21, 2014 Permalink | Log in to Reply

      Not actively working on devhub in general right now, because work and I probably won’t get to things that I am personally interested in in Parser until I get to revamping QueryPosts.

      Note that current stall on Parser is not much dry up in me doing things as dry up in contributions. A lot of it was driven by wonderful contributions, with me mostly merging PRs and making thankful noises. I do have capacity for latter at least (if not actively working on code at the moment), however there haven’t been any contributions lately.

    • J.D. Grimes 7:22 pm on August 21, 2014 Permalink | Log in to Reply

      I’ll see if I can find a little time to make some more contributions to the Parser. I’d really like to, it’s just a matter of being short on time right now.

    • Drew Jaynes (DrewAPicture) 2:43 am on August 22, 2014 Permalink | Log in to Reply

      I’m working on back-end features for editing Code Reference pages as well as explanations. I’m also looking into escaping non-markdown in inline docs. I might dive into the parser stuff a little bit to see if I can assist with some of the Posts2Posts integration stuff.

    • Nicole Arnold 6:39 pm on August 26, 2014 Permalink | Log in to Reply

      Commented on #449 & #197. Working on #542, then back to the others pending feedback.

    • Scott Reilly 7:00 pm on August 26, 2014 Permalink | Log in to Reply

      Since this post:

      • Committed changes to allow mixed text/code in examples. Also updated the content of all existing examples.
      • Committed dashicons resource page (http://developer.wordpress.org/resource/dashicons) — path subject to change). Fixed #252.
      • Committed change to use configured handbook name instead of post type label in page titles
      • Posted rough mockup for #493 (Add search form to internal pages)

      Working on:

      • Integrating @DrewAPicture‘s work which will get us explanations and:
        • #411 — Code reference content should only be editable by admins
        • #481 — Admins to enter core trac ticket number if editing parsed content
      • Voting for examples (#551)
      • #180 (Ability to submit examples on function pages) I guess would get formally closed once we open up submitting examples to any WP.org users (barring any feedback during its soft launch)
      • Minor tweaks here and there as they come up, such as for landing page, page titles, and handbooks
      • The usual of evaluating and merging any patches
  • Kim Parsell 2:14 pm on August 21, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Project Status Updates: August 21, 2014 

    DevHub project: please post your weekly status update in the comments of this post by the end of today.

    @samuelsidler posted the status update for the Handbooks project yesterday.

    If there are any other issues that need to be discussed, please add them in the comments as well.

    Team Office Hours will be from 17:00 UTC to 18:00 UTC today in #wordpress-sfd.

     
  • Samuel Sidler 11:35 pm on August 20, 2014 Permalink | Log in to leave a Comment
    Tags: ,   

    Handbooks Update: August 20, 2014 

    We had our weekly chat today with @blobaugh, @jerrysarcastic, @sewmyheadon, @topher1kenobe, and myself in attendance (log here).

    Both handbooks received quite a bit of attention during the WordCamp Grand Rapids and WordCamp Maine contributor days.

    Plugin Developer Handbook:

    • Some progress made over the last week.
    • A lot of things at 90%+ that need final edits.
    • Focus is on getting sections completed one-by-one.
    • Each section will need an “introduction” added. Some of them already exist.

    Theme Developer Handbook:

    • A second docs meetup in the Seattle area is going to be setup starting in October or so.
    • Eric would like a second person to help lead the handbook, specifically someone who can work with other volunteers.
    • Like the plugin handbook, we’ll need introductions for each section.

    For both handbooks, our focus is on getting things done faster and not making them “perfect.” We’ll edit as needed on the live site, but it’s important to get what we have in a usable state and get it live soon. Migrated pages will be blanked out on the staging site (make/docs) so we don’t modify them further.

    Finally, I updated the “Handbooks” page on the docs contributor handbook. That page and its subpages (including the style guide) need review and editing so we can help onboard new contributors.

    Would it help to have contributors join our weekly chats? Or perhaps to have a weekly, online handbook sprint? What does the docs team think?

     
    • Siobhan 3:37 pm on August 21, 2014 Permalink | Log in to Reply

      I’d find a weekly online sprint to be helpful. It would help me to schedule my time if I knew I had to set aside a few specific hours per week.

  • Siobhan 7:28 pm on August 17, 2014 Permalink | Log in to leave a Comment
    Tags: docs-handbook   

    Docs Handbook 

    I’ve done some work on the docs handbook. Here’s what I’ve done so far:

    Can any of you who are responsible for different projects take ownerships of the various sections? You can add your name in the handbook spreadsheet. The ones that come to mind:

    Whenever you feel like the content is ready for copyediting set it to 95% and I’ll copyedit it.

     
  • Kim Parsell 1:03 pm on August 14, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Project Status Updates: August 14, 2014 

    The feedback to my proposal last week was positive, so we’ll be changing to the new format starting today.

    DevHub and Handbooks projects: please post your weekly status update in the comments of this post by the end of today. I’ll use those to write the post for Make/Updates.

    If there are any other issues that need to be discussed, please add them in the comments as well.

    Team Office Hours will be from 17:00 UTC to 18:00 UTC today in #wordpress-sfd. See you there!

     
    • Samuel Sidler 1:16 pm on August 14, 2014 Permalink | Log in to Reply

      Devhub:

      • No update on Posts2Posts. If you’re interested in it, we need help.
      • Voting: Postponed for now while @coffee2code works on examples.
      • Proposal for dealing with content: Drew and Scott have been talking and Drew has offered to spearhead some of the changes needed.
      • Pull requests: Nicole’s pull request got merged in including the archive/search simplification. Other handbook design changes have been made as well.
      • Title tags: Scott added some, but it could use a think through so we can get it right (ping @siobhan)
      • Dashicons: @ryelle popped in to say she had worked on a page template for a dashicons page on devhub. She’ll move forward with building a page for it and attaching a patch so we can migrate it to devhub.
      • Bug scrub: It’s time to do another one, perhaps one in trac and one in Github (for the parser). Tentatively we’ll do one this coming Tuesday after the regular meeting. @siobhan will confirm if that works.

      Log is here.

    • Samuel Sidler 1:21 pm on August 14, 2014 Permalink | Log in to Reply

      Handbooks:

      • Short meeting, attended by @blobaugh, @topher1kenobe, and myself.
      • Plugin handbook spreadsheet: @topher1kenobe cleaned this up a bunch and it’s looking much more true to the state of things.
      • Plugin handbook: Chapter 17 (Helper Tools) was added. The WordPress.org section has been finished, pending final edit. Both of those are from @topher1kenobe.
      • Migration: I started migrating the theme handbook over (section 1 for now). There will be some handbook plugin/theme changes to make things look good, but we’re on our way. Part of that means cleaning up links along the way.

      Log is here.

  • Kim Parsell 6:27 pm on August 8, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Weekly Docs Chat Proposal 

    During this week’s chat, I proposed changing the format of our weekly Docs team chat on Thursdays.

    With each of us working on individual Docs projects, most of the discussion now takes place during the weekly project meetings, with a quick summary being given during the general chat on Thursday. As a result, the general chat has become just a check-in chat, rather than team discussion.

    I’d like to propose changing the weekly team chat on Thursday to general office hours from 1:00pm to 2:00pm EDT (17:00-18:00 UTC), so the team is available in IRC to speak with new contributors, or general discussion.

    For the team check-ins, I would make a post here each Thursday morning, asking for the status update for each of the projects. This would allow the teams to add their update in the comments (including a link to their weekly chat recap post), and any discussion of those updates can happen there as well. The updates would need to be posted by end of day Thursday. I can then use those responses, and the chat recap posts, to write the post for Make/Updates.

    I’d like us to use this P2 much the same way that the teams at Automattic use their internal P2 blogs – project chat recap posts, requests for feedback for individual projects, docs sprint reminders, etc.

    I think most of what we need to discuss during the weekly team chat we can do here, for now. This would also allow us to have one less weekly meeting on our calendars.

    If everyone is in agreement, we can start the new format next week.

    Thoughts?

     
  • Eric Amundson 10:04 pm on August 6, 2014 Permalink | Log in to leave a Comment
    Tags: ,   

    Handbooks Update: August 6, 2014 

    We had our weekly chat this afternoon (logs), with @blobaugh, @topher1kenobe, @sewmyheadon in attendance. Could have been others lurking too.

    Plugin Developer Handbook

    @blobaugh had some family issues that interfered with following up with contributors last week, but @topher1kenobe completed the Metadata section and it is awaiting review so we still have good forward momentum.

    Also, there we some contributions over the weekend at the Docs Sprint in Seattle by @awoods & @pjackson1972.

    @blobaugh will try to get Section 2 finished this week while traveling, but no promises.

    Theme Developer Handbook

    We also had contributions to the Theme Dev Handbook at our Docs Sprint in Seattle on Saturday, and inducted a few new Docs contributors and got them up to speed so they can help too.

    We made some good progress and Part One of the Theme Dev Handbook is nearly ready for prime time. We have three remaining articles in that section that need serious work, and they all need a bit more editing, but we should be able to move on within the next few weeks.

     
    • Christine Rondeau 1:28 am on August 7, 2014 Permalink | Log in to Reply

      Can you let me know which articles of the theme handbook need editing? I’d be happy to do this for you. I tried to do some writing, but I’m pretty crap at it. I’d be happy to edit one or two later this week.

  • Siobhan 8:04 pm on August 5, 2014 Permalink | Log in to leave a Comment  

    Devhub update 5th August 

    Thanks to everyone for coming to the meeting. Here’s what we discussed:
    1. WP-Parser. We’re still trying to get P2P implemented in WP-Parser. We’ll get there eventually.
    2. Voting. @coffee2code is working on the voting functionality.
    3. We discussed the proposal for dealing with content in the code reference. Everyone seems happy with it. Waiting for feedback from @drewapicture and then @coffee2code will work on implementation.
    4. @nicolealleyinteractivecom sent a pull request for the handbooks. @coffee2code will review and implement.

     
  • Siobhan 7:00 pm on August 5, 2014 Permalink | Log in to leave a Comment
    Tags:   

    Content in the Code Reference 

    Below is a proposal for user-generated content in the code reference.

    • Individual code reference pages are split into three sections:

    — parsed content
    — officially curated content
    — user-generated content

    Much like this diagram:

    • Parsed Content will come from the parser
    • Officially curated content will be added by the docs team
    • User generated content will be added by users and filtered via voting.

    Here are some mockups:

    Function page with curated content

    Function page with user-contributed note input expanded

    Function page with user-contributed note

    Full gallery is here:

    https://cloudup.com/cUO0KGdF43p

    This will involve two major changes:

    • examples will become user-contributed notes. These should be able to deal with both code examples and text
    • we will need a way for the official docs to be added. My instincts are that these should be added to the content editing section in the back-end, but at the minute the parsed content is added there. So I’m not sure what the best way to technically implement this is.

    I’m definitely open to changes so please make suggestions.

    Thanks to @boone for input into this.

     
    • Rami Yushuvaev 10:12 am on August 6, 2014 Permalink | Log in to Reply

      Looks great!

      You mentioned that user generated content will be added by users and filtered via voting.

      1. What about the content in the codex?

      2. Why voting? the codex don’t have spam.

      3. What about the TOC?

      Rami Y.
      GenerateWP.com

      • Siobhan 8:23 pm on August 6, 2014 Permalink | Log in to Reply

        1. Reference Content in the Codex will be moved over to the code reference (and edited on its way there)
        2. It’s not related to spam – it’s to ensure that good-quality examples and use cases rise to the top. It’s fairly standard in other code references.
        3. There is no TOC – it’s a reference. The theme and plugin developer handbooks have TOC.

    • Drew Jaynes (DrewAPicture) 5:33 pm on August 7, 2014 Permalink | Log in to Reply

      I like this. I think we’ll definitely need to fine tune the experience in regard to submitting and interacting with the user notes at the bottom, but the hierarchy seems sound. I was a little skeptical of trying to inject explanations with the parsed content, so I think is a good solution.

      As for the question about where to enter the “explanation” content, I think I agree that I’d like to see use the main editor for that, maybe dropping the parsed content into meta or the excerpt or something.

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