WCSF Contributor Day

We’ve made plans to work on completing both the developer handbooks during our two day team meetup following WCSF.

I’d like to use this thread to discuss ideas on what Docs tasks we can have contributors work on during Contributor Day on Sunday.

This is a good opportunity to have contributors work on non-handbook tasks that also need to be completed.

A couple possibilities are:

  • Code Reference Migration: migration of content from the Codex code references to the new code reference, including reviewing content, adding examples, and setting up redirects from the Codex.
  • Codex cleanup: review of Codex content – editing, truncating, deleting pages that are out of date.

If you have other suggestions, please add them in the comments. Also indicate whether you’ll be available to work with new contributors on Sunday.

#contributor-day, #wcsf2014

Learned about helping out and getting started with…

Learned about helping out and getting started with documentation this past weekend at WordCamp LA. Edited my first page in the theme handbook and looking forward to digging in some more 🙂 I’m a designer, not a developer, so I’m focusing on clarity and ease of understanding, consistency in formatting, etc.

I do have some questions about formatting for consistency, such as:

  • Sometimes things are capitalized and sometimes the same thing isn’t … so, what should be capitalized and what should not? (i.e. post, page, Post Type, Custom Post type)
  • In a list of items, if not in a bulleted list, do you want the comma used before the “and” or not?
  • In a bulleted or numbered list, should each item have an initial cap or not?
  • And regarding consistency in bolding, should code references (i.e. post_type) use a bold or regular style?

I’m sure I’ll have other questions as I go, but I’m looking forward to digging in, reading all your hard work, & learning! Oh, and please let me know if I do something wrong or mess anything up … just a little nervous about getting started 🙂

#contributor-day

I’m at WordCamp LA Contribute day We’re looking…

I’m at WordCamp LA Contribute day. We’re looking over pages and cleaning up typos and language (not finding many problems) I’ve been looking at pages for The Loop, Theme Functions, etc

#contributor-day

Contributing this fine WordPress Weekend

There are two events particularly relevant to the docs team coming up this weekend:

WP Contributor Day in Manchester, UK

The newly formed WP Contributor Day group is running their first event on March 1st from 10AM – 6PM UTC, @johnbillon has written a post with more details. The event’s site is at WPContributorDay.com.

For docs folks in particular, if you’re in the north of England, why not head on over? It’s sure to be a great day, whatever your skills or experience level.

If you’re elsewhere, and already familiar with contributing then joining in virtually via #wordpress-sfd would be a fantastic thing to do.

Monthly Docs Sprint in Seattle, USA

The Seattle Meetup group are hosting their monthly Docs Sprint on Saturday, too. It’s running from 10AM – 2PM PST.

It’s been a while since we’ve mentioned the additional virtual nature of these sprints here on the blog, so for the benefit of newer contributors, here’s some of the backstory.

In short: the meet-up group welcomes your participation, wherever you may be!

To quote @sewmyheadon, here’s what do to if you’re not in the Seattle area:

Online: If you’re bashful, or simply outside of the Seattle area, you can simply logon to the IRC channel at #wordpress-sfd and participate from anywhere.

Why not take a peek at the getting started page for the handbooks to gather inspiration for your contributing this coming weekend?

Happy weekend, docs!

#contributor-day

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

WordCamp Providence Contributor Day

Here are some tasks from the Theme Dev Handbook that can be carried out on docs at the Contributor Day at WCPVD:

Need to be written:

  • Media: https://make.wordpress.org/docs/theme-developer-handbook/theme-functionality/media/
  • Post Thumbnails: https://make.wordpress.org/docs/theme-developer-handbook/theme-functionality/post-thumbnails/
  • Theme Security: https://make.wordpress.org/docs/theme-developer-handbook/advanced-theme-topics/theme-security/
  • Theme Options: https://make.wordpress.org/docs/theme-developer-handbook/advanced-theme-topics/theme-options/

The following pages need to be expanded:

  • Theme Customizer: https://make.wordpress.org/docs/theme-developer-handbook/advanced-theme-topics/theme-customizer/
  • Custom Headers: https://make.wordpress.org/docs/theme-developer-handbook/theme-functionality/custom-headers/

The following pages need to be reviewed and edited:

  • Internationalization and Localization: https://make.wordpress.org/docs/theme-developer-handbook/theme-functionality/translation-and-internationalization/
  • Pagination: https://make.wordpress.org/docs/theme-developer-handbook/theme-functionality/pagination/
  • Comments: https://make.wordpress.org/docs/theme-developer-handbook/theme-functionality/comments/

The following will come in useful:

#contributor-day