Codex Audit & Docs Sprint

@jhoffm34 and I have been reviewing the content in the Codex. I exported all of the pages from Google Analytics and then we’ve sorted them into groups of similar content types to see what emerges. You can view the spreadsheet here: https://docs.google.com/spreadsheet/ccc?key=0AnxB9WffF3jOdEFWYWozTGtvNlQ5WGFTQTAxTG55R0E&usp=sharing

The content we analysed broke down broadly into these different areas:

User

  • Installing WordPress
  • Getting Started
  • Glossary
  • Blogging
  • Site Builder
  • Troubleshooting
  • MultisiteMultisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core.https://codex.wordpress.org/Create_A_Network.
  • Administration (inc Security?)
  • Getting Help

There are also about 60 reference pages for the various Panels/Screens. e.g. https://codex.wordpress.org/Administration_Panels

Developer

  • Setting up a Development Environment
  • How WordPress Works
  • Troubleshooting
  • Code Reference
  • 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 Developer
  • Theme Developer
  • Server
  • Multisite
  • Administration

I am keen to have a strict division between the user-focused material and the developer-focused material. Of course, there are times when a developer will be a user (when they are managing their website) and there are times when a user will be a developer (when they tweak their theme) but linking between resources is more effective than putting the user and developer material together.

I’m reluctant to make major plans for restructuring and changing everything around before we close the Codex survey and analyse the results (some of which are surprising i.e. not everyone hates the Codex), however, I would like to come up with some concrete tasks for the Docs Sprint in a few weeks.

Therefore, I suggest that the team at the docs sprint tackle the following handbooks that can be built on learn.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/:

  • Site Builder Handbook
  • Blogging Handbook
  • Editor Handbook
  • Theme Developer Handbook

Thoughts? Complaints? Suggestions?

#codex, #sprint

3.6 Master Codex changes list (in progress)

Since we’re revving up for the 3.6 release and a Codex Sprint, this post will serve as our “master changes list” for 3.6. This list is by no means complete, so leave a comment if you feel like something is missing. We’ll update it as we go. If you’ve completed a todo item, let us know and we’ll check it off for you.

Pages

  • Revision Management [ current ][ new draft ] Ref: #23497 (mostly technical)
  • Menus Administration Screen [ current ] Ref: #23607 (Tracking ticket)
  • Menus User Guide [ current ] Ref: #23607 (Tracking ticket)
  • Post Locking [ current ] Ref: This is more of a UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ‘what they are doing’ and less about how they do it. change. Users now have to consciously override the post lock, vs before you could just open something if somebody was editing it.
  • Function Reference update the Function Reference with new functions.

General

Version 3.6

Twenty Thirteen

oEmbeds

Media

Function Changes

  • Strip slashes from passwords sent to new users by email
  • Make sure the url returned by post_preview() is filterable with preview_post_link
  • An arg parameter was added for wp_nonce_url()
  • Allow paths with two consecutive dots to be passed to home_url() and all related *_url() functions
  • Document 7th parameter, $callback_args in add_meta_box()
  • Confirm a user exists before deleting them in wp_delete_user() and wpmu_delete_user()
  • Return WP_Error from wp_crop_image() if saving has failed
  • Bail early with correct WP_Error if invalid post ID passed to wp_insert_post()

MultisiteMultisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core.https://codex.wordpress.org/Create_A_Network.

  • Pass blog_id to the wpmu_drop_tables filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.

Class Changes

  • XML-RPC: Return an error for getRecentPosts (mw and blogger) if the user does not have edit_posts cap
  • XML-RPC: Standardize home/site url labels with coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. labels

‘needs-codex’ TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. tickets

>> Look for the Trac comment where needs-codex was added for more info

  • #11446 – Show ellipsis after truncated filename in Media dialog
  • #13578 – wp_link_pages isn’t fully functional and doesn’t include require style information
  • #15081 – Search Form should use type=’search’
  • #15155 – Allow filtering of 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. attributes
  • #16738 – Add filter for attributes on menu item links
  • #17515 – Flaw in add_meta_box/do_meta_boxes
  • #19067 – Duplicate functionality in core: size_format() and wp_convert_bytes_to_hr()
  • #19210 – Add missing filters to remaining link(url) functions in feed.php
  • #19321 – get_search_form() function calls an action and a filter with the same hook.
  • #20564 – Framework for storing revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. of Post MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.
  • #22187 – Add docblocks to wp-signup.php
  • #22885 – Correct the PhpDoc for the_post_thumbnail
  • #22905 – PhpDoc refresh for register_sidebar()
  • #22913 – “Files “”corrupted”” when streamed to file via HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.
  • #23058 – Corrected inline docs for cache.php
  • #23119 – UX Improvements to nav-menus.php
  • #23121 – Correct inline doc return value for WP_Filesystem_Base::gethchmod
  • #23313 – inline doc additions in wp-includes/formatting.php
  • #23325 – wp_crop_image does not return WP_Error when save fails
  • #23508 – Nav Menu Saving: get_nav_menu_locations() can return false, code expects array
  • #23641 – Tweaks to menu management box
  • #23770 – Restore ‘Locations’ meta box functionality as secondary tab in Menus 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.
  • #23791 – Missing param in wp_get_attachment_image() docs
  • #24203 – Remove the_title_attribute() from anchors with the_title() as text
  • #24265 – Clean up revision.php docblocks
  • #24314 – Documentation Improvement wp_dashboard_quota
  • #24343 – Correct inline docs for hook parameters in wp_delete_term()

New Functions

Audio / Video

Media

Revisions

General

New Filters

Deprecated Functions

External Libraries

  • Update to jQuery Color 2.2.1
  • Update to Backbone 1.0.0
  • Update to jQuery UI 1.10.3
  • Services_JSON 1.0.3
  • Iris 1.0.3
  • hoverIntent r7
  • MediaElement.js 2.11.1 (New)

#codex, #release, #sprint

Open Help Conference and Sprints

At the docs chat last week I raised the possibility of having a documentation sprint at the Open Help Conference in Cincinnati in June. The conference is two days on 15th & 16th June, followed by a three day documentation sprint from 17th – 19th June. The great thing about doing it here is that we get to meet and learn from other OS documentation projects such as Mozilla and Gnome. Also, the venue and all of the practicalities are taken care of for us. We’ve just got to write.

I would like to bring a team of WordPress people out there to run a documentation sprint to tackle the following tasks:

  • completing the theme and 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 developer handbooks
  • populating and organising the new code reference
  • possible other project depending on who attends and how many people we have.

The aim is for high impact in a short space of time. I’m open to suggestions for other projects so please feel free to run them by me.

I’m looking for both writers and developers to come along. So if you’re a developer and you’ve always wanted to get involved with docs, we would love to have you.

There will be some funding available but this will be largely for people who have already gotten involved with the WordPress project. I have gotten in touch with some WordPress businesses already, who have said that they will send an employee. So ask your boss – or ask me to ask your boss 🙂

If you run a WordPress business and you’re reading this, this is a great opportunity for an employee to improve their documentation skills while giving back to the project.

If you are planning to come, please keep in mind that this will be a working trip. You will be writing for three days, although we should have time to to squeeze in a bit of fun somewhere (not that writing documentation isn’t fun!)

Please fill in one of these two forms:

I’m going to be figuring out my budget this weekend so the application for financial assistance will close on Saturday 22nd April, 23:00 UTC. I’m happy to answer any questions on the thread here, or in the chat on Thursday.

Note: please don’t book tickets to the conference until everything is finalised

#open-help, #sprint

WordPress Codex Sprint Round-up

The first WordPress codexWordPress Codex Living online manual to WordPress.org https://codex.wordpress.org/ sprint was a success! A bunch of us got together in the #wordpress-sfd chatroom and ploughed through the majority of the docs. You can see how successful we were by checking out our to-do list.

There are a few things left on the list so if anyone could tackle them and let me know so I can tick them off that’d be great. The final bits and pieces are developer docs.

Some things that we learned:

  • documentation sprints are a great way to get through a lot of documentation at once.
  • it is important to have some developers involved who can deal with the ultra-developer stuff and field questions

Anyone learned anything else? Add it to the comments so I can add it to the list.

Thanks to the following people for working hard to get the docs updated: Jerry Bates (@jerrysarcastic), Jonathan Wold (@sirjonathan), Philip Erb (@philerb), Curtis McHale (@curtismchale), Mika Epstein (@ipstenu), Jason Hoffman (@jhoffm34), and Marko Heijnen (@markoheijnen)

Special thanks to Drew Jaynes (@drewapicture) who hasn’t just been a rockstar, he’s been a superstar. Thanks Drew!

Future Sprints

I’d love to see more documentation sprints in the future. As well as having them virtually, they could be organised at WordCamps to coincide with developer activity. Some ideas for future sprints:

  • updating the function reference and making sure that everything has examples
  • cleaning out old content
  • updating out-of-date pages
  • re-working the FAQs
  • making a dent in the handbooks
  • working through the Help Tabs

If anyone else has any suggestions for future documentation sprints, and how often they think they should be, do leave a comment!

#codex, #sprint