Tag Archives: spec

Samuel Sidler 8:38 pm on January 13, 2015
Tags: helphub, spec   

Helphub Spec

At the WCSF community summit in October, one of the things we discussed was a support “hub” –  affectionately called “helphub” by @ipstenu – to replace support-related Codex pages and to act as the front page of WordPress support, likely living in front of 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//support forums. In many ways, helphub is meant to mirror similar efforts by other organizations, like Apple, Disqus, Google, MailChimp, Media Temple, Mozilla, and countless others. Below is a general overview of what we talked about to get things started.

Goals

Helphub has a few goals:

  • Replace support content (mostly on the Codex) with high quality, easy-to-understand articles.
  • Create a searchable repository that makes it easy for users to find content.
  • Reduce the amount of support forumSupport Forum WordPress Support Forums is a place to go for help and conversations around using WordPress. Also the place to go to report issues that are caused by errors with the WordPress code and implementations. posts by making it easier to find answers in helphub.
  • Provide a reference that support forum volunteers can link to for common questions

Stakeholders

The major stakeholders in the project are:

  • the support team – it will be tightly integrated with the support forum
  • the docs team – who will write and maintain the content
  • the 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. team – who will build and maintain the site

Solutions

To meet the goals listed above, we discussed two solutions:

  • A “knowledge-base”-style support section with high quality articles.
  • A powerful search feature for the knowledge base.

At the same time, it will be important to improve the support forums in ways that complement helphub.

Components

Helphub consists of three components:

  1. Content
  2. A knowledge base on WordPress.org
  3. Search

Content (Articles)

The success of helphub rests on great content. In order to generate this content we will:

  • Review analytics from the Codex to determine the most viewed pages.
  • Review analytics from the support forums to see what questions are most asked.
  • Ask support volunteers to generate a list of the articles they would find most useful
  • Ask WordPress businesses that provide support to their customers what the most common questions are.
  • From the above analytics, create a list of the top n articles that need to get written.
  • Put together a standard template for knowledge base articles.
  • Put together a KB style guide.
  • Start writing articles with end users in mind.

Until the knowledge base is built, we will need to host this content somewhere. There should be at least 15 articles created before the design phase starts, to provide the designer with content to work with.

Knowledge Base

The knowledge base should have the following features:

  • Good integration with the forums:
    • For example, a link that says “Still have questions? Click here to ask your question to a volunteer in the support forums.”
    • When a user starts typing a question in the support forum, a list of possible KB articles should be suggested.
    • A solid taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. system. Content should be flagged according to experience level (e.g., beginner, advanced, etc) and it should also be tagged with specific areas (e.g. wp-config, media, 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.).
    • A quick way for forum volunteers to link to articles in the KB.
  • A “Did this article help you?” yes/no button to gauge the helpfulness of knowledge base articles.
  • Perhaps, the ability to leave feedback (comment) on an article. Comments would be private and allow an article editor to fix any issues.
  • A “related topics” feature.

To get to this point, we’ll need to:

  • Review other knowledge bases to determine which features work well.
  • Contact the leads of other knowledge bases (especially those in the 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. community) to see what works for them.
  • Create a detailed list of features needed for our knowledge base.
  • Develop wireframes from articles (see the content section above) along with our feature list.
  • Create mockups from the wireframes.
  • Determine the appropriate WordPress 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 structure.
  • Develop a WordPress plugin to run our knowledge base.
  • Develop the mockups into a WordPress theme.

After this, we’ll need to fill the knowledge base with the content above.

Search

Good search is crucial to a good knowledge base. We will need something more powerful than the current search on WordPress.org. Rather, we should use elastic search to provide the best answers for users. To ship an effective search engine:

  • Determine the best search engine to use.
  • Develop the search engine.
  • Test and tweak the search engine.

We’ll probably rely a variety of other elastic search users to make this possible.

#helphub, #spec

Samuel Sidler 12:37 am on September 12, 2013
Tags: docs issue tracker, , spec   

Documentation Issue Tracker Specification

The Docs team tracks, modifies, and improves documentation across the WordPress project including in: CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., the Codex, the upcoming Handbooks, and other parts of 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/ and related websites. Throughout the project, code and design issues get tracked in tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. (both the core and 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. tracs), but this method isn’t the most efficient for tracking documentation issues. Thus, a documentation issue tracker has been proposed by the Docs team.

Goals

The documentation issue tracker has two main goals:

  • easy reporting of issues throughout the project to Docs team
  • easy tracking of reported issues

A successful documentation issue tracker ultimately will improve documentation throughout the project.

Stakeholders

The docs team is the major stakeholder for this project, given they will be primarily using the tracker.

An owner is needed.

@samuelsidler will project manage and work with the docs team and owner.

Solutions

There are two major features to a documentation issue tracker:

  1. reporting interface
  2. tracking interface

To ensure we complete our goals, we’ll use the following metrics:

  • user tests of end users reporting documentation issue (to ensure it’s easy)
  • feedback from Docs team for tracking

Components

As stated above, there are two components to the documentation issue tracker: Reporting and Tracking.

Reporting

The reporting interface will need to collect a bit of information automatically (when possible) for submission to the tracker. Specifically, we’ll be collecting the username of the reporter, the date an issue was reported, an issue type (user selectable), link to page (using the referrer, when possible), and a custom, user-created description. Users will need to be logged into their wordpress.org account to file an issue. If they are not logged in, we’ll redirect them to the login page first. There may be interactions that break here, for example the referrer may get lost if a user has to log in before reporting an issue.

We still need to determine where this reporting interface will exist (only on a specific page or a link everywhere?)

Completed Steps:

  • determined more details about the what information to collect and when
  • @karmatosed designed reporting interface
  • initial mockups posted for feedback
  • final mockup created
  • @Otto42 has agreed to develop the reporting interface

Next Steps:

  • work with the Docs and Meta teams to determine where the interface will live

Tracking

The tracking interface will be used mostly by the Docs team to track incoming and active issues. Part of this interface involves viewing issues individually and changing their status. Editors (or Gardeners) will need specific permissions to make actions. More specifically, we will require users to have the “Editor” user role to resolve issues.

On the tracking interface, we’ll want to display the following information: username of the reporter, the date an issue was reported, issue type, link to page, person assigned to an issue, a button that assigns an issue to you, and a resolve check box. A user-created description will exist and can be revealed with a “reveal arrow.”

Completed Steps:

  • made decisions about specific information required and user roles that will be able to resolve issues
  • @karmatosed designed tracking interface
  • initial mockups posted for feedback
  • final mockup created
  • @Otto42 has agreed to develop tracking interface (possibly using P2P2 P2 or O2 is the term people use to refer to the Make WordPress blog. It can be found at https://make.wordpress.org/. with the resolved posts 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)

Next Steps:

  • determine where tracker will live

Note: As it stands right now, this issue tracker will likely have a one-size-fits all tracking interface and not allow much customization as far as tracking. However, eventually we will want to allow sorting by “component.”

#docs-issue-tracker, #projects, #spec

Samuel Sidler 4:59 pm on August 14, 2013
Tags: , , spec   

developer.WordPress.org Specification

developer.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/ is a new portal for WordPress developers. It will provide educational tools to teach people about WordPress development (in the form of handbooks) and a reference for the WordPress codebase (the code reference).

Goals

developer.WordPress.org has several goals:

  • improve current resources for developers
  • encourage best practices in WordPress development
  • educate new developers

If the site succeeds at encouraging best practices in WordPress development, a potential side-effect is an improvement in users’ experience of third party plugins and themes.

Stakeholders

The primary team identified as a stakeholder is the docs team. However, three other teams are associated stakeholders and their input will be used in the development of the resources. They are: coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., themes, and plugins. The net result of a successful implementation means improved documentation and educational information for new, intermediate, and experienced developers, ultimately affecting the entire project.

@siobhan has volunteered to own this project.

@samuelsidler will project manage and work with the above stakeholders (e.g., communicate with the team reps from each team).

Solutions

We’ve identified two features of the developer portal that will complete the goals of this project:

  1. developer handbooks
  2. code reference

To ensure we complete our goals, we’ll use the following metrics:

  • stats from the both the code reference and handbooks to ensure they’re being used
  • feedback from the development community by way of surveys, comments, and weekly meetings
  • full testing of handbooks by amateur developers; they should be able to work through the handbooks and achieve the individual handbook’s goal by the end.

Components

developer.WordPress.org can be broken up into three components, each with their own specific tasks.

Design

Designs need to be created for:

  • main landing page
  • handbook landing pages
  • individual handbook pages

Completed Steps:

Next Steps:

Handbooks

Two handbooks are currently in progress and are pivotal to the success of this project. Both are being spearheaded by @hanni.

Other handbooks have been proposed, but are not required to complete this project:

  • Introduction to WordPress Development
  • Server Configuration for WordPress
  • Building Networks with WordPress 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.

developer.WordPress.org should launch with 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 complete. More contributors are needed in this area to assist with writing, developing, editing, and testing the handbooks.

Next Steps:

  • review current handbook content
  • push handbooks to developer.wordpress.org with basic design (as seen on core contributor handbook); starting with theme dev handbook which is furthest along
  • @hanni to draw up further plans

Code Reference

Development of the code reference is currently in progress.

Completed Steps:

Next Steps:

The inline docs are going to be updated by the core team in 3.7 to ensure that we get a good output. Once the alpha is up and running we’ll need a team around making improvements to it. This will include:

  • ongoing development of the parser
  • extending the functionality (we’ll use meta.tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. for features, enhancements, bugs, so people can upload patches)
  • testing the workflow to make sure that people can contribute explanations and examples
  • moving relevant information from the Codex
  • having a drive to get people to add information
  • ongoing curation and moderation

#devhub, #projects, #spec