Handbook Tasks – WordCamp Sofia Contributor Day 2013

Howdy WordCamp Sofia Contributors!

Thanks a bunch for helping with WordPress documentation – we all really appreciate your help!

We’ve been focusing a lot on the Theme Developer Handbook and Plugin Developer Handbook, which both need a good deal of work.

For most people, the toughest roadblock to contributing is just getting started, so hopefully this will help.

Where to Go

The jumping off point for all docs-related efforts is: make.wordpress.org/docs/ – In the sidebar, you’ll see links to the Handbooks along with the Spreadsheets we use to track their progress.

  1. The Theme Developer Handbook is at: http://bit.ly/WPThemeHB
    • . . . and the spreadsheet that we use to track Theme Developer Handbook progress is at: http://bit.ly/WPThemeHB_Content
  2. The Plugin Developer Handbook is at: http://bit.ly/WPPluginHB
    • . . . and the spreadsheet that we use to track Plugin Developer Handbook progress is at: http://bit.ly/WPPluginHB_Content
  3. The IRC channel we use is at #wordpress-sfd on Freenode.
    • This is a great place to ask questions, post links to docs for review, and cheer each-other on.

Getting Started

If you haven’t already, you’ll want to:

  1. Read the Handbook Style Guide
  2. Review the Handbook Tutorial Template
  3. Find a topic in the Theme or Plugin developer spreadsheet that interests you
  4. Check the Needs column of the spreadsheet to see if there are specific things that are needed in this document
  5. Add your name to the Responsible column in the spreadsheet
  6. Write or edit in HTML or Markdown and give it to Mario Peshev or email it over to me at eric [at] ivycat.com and we’ll post for you.

What if I’m not a Writer?

If you’re not comfortable writing or editing, you can also help by:

  • Creating code snippets for examples
  • Taking relevant screenshots
  • Reading existing documentation and making comments regarding improvements

If you’re completely overwhelmed and not sure where to start, you might start by reading through the Handbook and, when you’ve got questions, find missing content, or see improvements, please feel free to work on the document, or make comments in that document’s comment section.

I’m here to help in any way I can, so feel free to ping me (@sewmyheadon) or Mario (@no_fear_inc), or post to the #wordpress-sfd IRC channel if you have any questions.

Thanks again and have a great WordCamp!

#contributor-day, #docs, #wcsofia

Inline Docs Tasks – WC Sofia Contributor Day 2013

For those of you contributing to Inline Docs during Contributor Day Sofia 2013, we thank you. 🙂

The Inline Docs initiative is a part of the overall effort to build a new code reference that will live at developer.wordpress.org. Creating inline documentation for hooks will provide the information necessary to populate that portion of the code reference.

What You Need To Know

Please read the PHP Documentation Standard section on documenting Hooks (Actions and Filters) to familiarize yourself with how the actual doc block should be formatted, and how duplicate hooks should be documented.

  • The Documenting Tips section covers recommended language when writing descriptions, as well how to determine the version for @since, and guidelines for Code Refactoring.
  • The Formatting Guidelines section covers how to format the text in the descriptions.

Opening A Ticket > Getting Started > Trac Preferences explains how to log in to Trac with your WordPress.org username, and how to configure your email address in Trac preferences so that you receive Trac ticket notifications.

Working With Patches covers creating patches using the command line and TortoiseSVN (for Windows users). If you are using Git, please follow the creating patches guide at Contributing to WordPress Using Github by Scribu.

How to Contribute

We have reserved 15 files for the WC Sofia contributors to work on, and have tagged them (Reserved-WC Sofia) on the Add Inline Docs for Hooks post. The files are:

  • wp-admin/network/edit.php
  • wp-admin/network/settings.php
  • wp-admin/network/site-new.php
  • wp-admin/network/site-settings.php
  • wp-admin/network/users.php
  • wp-admin/user/admin.php
  • wp-admin/includes/export.php
  • wp-admin/includes/menu.php
  • wp-admin/includes/template.php
  • wp-admin/includes/theme.php
  • wp-includes/functions.wp-scripts.php
  • wp-includes/functions.wp-styles.php
  • wp-admin/press-this.php
  • wp-admin/update.php
  • wp-admin/user-edit.php

The following are the steps you need to follow:

1. Leave a comment on the Make/Core post with the name of the file you are going to work on.

2. Update your local WordPress SVN or Git repo (use git pull) to the latest version of WordPress trunk (currently 3.8-alpha).

3. Create a new ticket on Trac for the file.

new_docs_ticket_labeled

  • Format the title as “Hooks Docs: path/to/file.php”.
  • The Type should be “defect (bug)”.
  • Assign the ticket to the “Inline Docs” component.
  • Leave the Version blank.
  • The Severity should be “normal”.
  • Add your wordpress.org username or email address to the CC: field so you’ll receive activity notifications for your ticket.

4. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.

5. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

Patch Review Process

1. We will review your patch, and may make recommendations for changes that need to be made. We will change the ticket keyword to “needs-patch” if changes are needed.

2. Please read the review, ask for clarification if needed, then make the requested changes, and create a new patch.

3. Use the same filename for your revised patch, and upload it to the ticket. Remove the “needs-patch” keyword, and add the “has-patch” keyword.

  • Note: Do not check the box next to Replace existing attachment of the same name – it is preferred to have copies of all attachments submitted to preserve the history of the ticket. Trac will automatically append an incremental number (xxxxx.2.diff) to the end of a patch filename to prevent an accidental overwrite of the existing file, in cases where the same patch is submitted multiple times due to needed changes.

We will review the updated patch, and may request further changes, if needed. Repeat steps 2 and 3 until we say your patch is good, and we tag it as “commit”.

Congratulations, and thank you for contributing to WordPress! 🙂

#contributor-day, #inline-docs, #wcsofia