Docs Chat: 17 October 2013

@sewmyheadon is away at a conference, and asked me to lead the chat today in his absence.

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 discussed.

1. Internationalizing Codex/Docs Code Examples

Prompted by a discussion on Twitter, @siobhan asked on Make/Polyglots whether all code examples in the Codex and other official WordPress documentation should be internationalized. There was already quite a bit discussion in the post’s comments prior to the meeting.

@nacin said the two primary issues with internationalizing code examples are: (1) increasing the barrier to entry for new developers; and (2) use of the internationalization function doesn’t actually internationalize the code. (see his full comment here)

@xibe proposed that we provide a link to the i18n Codex page at the bottom of every code example with translatable strings saying, more or less, “Code is simplified for readability reasons. Production code should have all the strings internationalized.”.

That seems to be the best option for now. We’ll be putting out a call for someone to review the code examples, and add text to ones with translatable strings, say that they are examples, and should be internationalized when used in production code, plugins, or themes.

2. EPub Docs

@siobhan had an email from someone who has offered to publish the WordPress docs in epub format. Mike (mac2net) joined us in IRC to discuss the offer, and how it would work. Unfortunately, it currently involves the software running on an external server. @sams and @siobhan both stated that we can’t (a) use an external service, or (b) use non-open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. code. @sams and mac2net will be continuing the discussion over email to see if the obstacles can be worked out so that everything runs on the 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/ servers, and report back on the progress during next week’s chat.

3. Inline Docs

Discussed at this week’s devhub meeting are changes that need to be made in the PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. Docs Standard to incorporate markdown into the doc blocks to fix formatting issues when they are run through the parser. I’ll talk with @rarst to verify the requirements, then we’ll get the standard updated. We noted at yesterday’s Inline Docs chat that we’ll also review the already-submitted patches for any changes that may need to be made. Current status: 72 files completed, 184 files total (39.1%).

4. WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Sofia Contributor DayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/.

@nofearinc asked on Twitter today if there’s anything in particular that they can help with during the WordCamp Sofia Contributor Day, scheduled for 10/27/2013. I’ll work on a list of Inline Docs tasks. @hanni and @sewmyheadon will put together a list of tasks for the 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/theme developer handbooks.

5. WordPress 3.7

@siobhan asked about Codex/Docs tasks that need to be completed before 3.7 is released. @drewapicture has already volunteered to write the 3.7 page in the Codex. A new page needs to be written about the automatic updates, with a section for users (explaining how they work) and a section for developers (under the hood goodies). Depending on the length/complexity, it may be best to split it out into two pages.

6. devhub

@siobhan said that all is going well with the devhub project. @toscho and @krogsgard have joined the team. @toscho and @rarst are doing the code reference development. @krogsgard will be building the new theme for developer.wordpress.org.

7. Handbooks

@hanni reported that she gained two new contributors for the plugin developer handbook at WordCamp Europe. Progress was made on the handbook during their contributor day, and she is currently reviewing the contributions.

And that wraps up this week’s chat summary. @sewmyheadon will be back for next week’s chat on Thursday at 16:00 UTC.

#chat-recap