Performance Co-Pilot

Task-based Guides for Performance Co-Pilot

About Performance Co-Pilot

Performance Co-Pilot (PCP) is an open-source distributed system performance analysis toolkit. It efficiently collects metrics from multiple systems and provides a variety of web, graphical and console tools for analysis of live and historical data.

The suite begun production use over 20 years ago primarily in the High Performance Computing arena, however its customizable and lightweight design has proven popular on everything from tiny system-on-a-chip machines through to vast databases and number-crunching super computers. It is included in all Linux distributions and has an active base of users and developers.

Writers interested in contributing to the project described here are encouraged to contact the volunteers listed below, and join the PCP community for further discussion.

Participants

Volunteers: Apurva Bhide , Christian Horn and Nathan Scott

Three volunteers have come forward to assist once again - a PCP maintainer, a developer and a documentation specialist - all of whom volunteered last year as well.

About Task-based Guides

In our previous Google Season of Docs project, we converted two freely-available books (the "Users and Administrators Guide" and the "Programmers Guide") into pcp.readthedocs.io content. We also extended this documentation with a new REST API guide, and made many other improvements.

However, due to the many available tools, daemons, integrations and APIs we still find a high barrier to entry for new PCP users.

It is this we plan to tackle next with our writer - curating a new series of focussed, task-oriented "How To" guides that will assist new users in engaging immediately, by clearly showing how to solve specific problem scenarios that users encounter frequently.

The goals of the project are this to assist first-time users to become more productive right away, while also increasing traffic to the more detailed books in the same location (readthedocs.io). We plan to undertake this project over three months.


The Task-based Guides project will:

Pair developers with the writer to produce succinct step-by-step recipes showing how to perform certain tasks with PCP.

Task-based topics include:

How do I ...

  • List the available performance metrics?
  • Add new metrics to the available set?
  • Record metrics on my local system?
  • Record metrics from a remote system?
  • Graph a performance metric?
  • Automate performance problem detection?
  • Setup automated rules to write to the system log?
  • Record historical values for use with the pcp-dstat tool?
  • Export metric values in a comma-separated format?

Additionally, the writer will:

  • Canvas the community for additional topics beyond the set above to produce an initial set of high-value guides
  • Provide feedback to developers about potential areas of improvements in the tools to create more satisfying early user experiences.
  • Audit existing documentation for tutorial content to add into the new readthedocs guide format. This involves an assessment of the existing Short Guides and refactoring these into the "How do I..." form.
  • Introduce consistency into all Tutorials and Guides across the project, by using a single readthedocs.io landing page for all guides (same location, format, look-and-feel).

Work that is out-of-scope for this project:

This project will focus on core PCP functionality, and not on integration with (for example) 3rd party sources of metrics, or sending PCP metrics to other analysis systems.

Measuring Success

We anticipate the How To pages will provide a better suited entry point for both new and some existing users. We will measure this by first enabling Google analytics on our readthedocs pages to begin tracking page accesses.

Success will be indicated by:

  • The largest number of hits to documentation pages being to the new Task-based Guides pages (we expect greater than double any other books as a measure of success). This success measure will be presented as a graph showing the spread of hits, with the most being attributed to the new Task-based Guides.
  • A correlated increase in the number of hits to the existing PCP documentation - the Users Guide , Programmers Guide and REST API Guide as a result of the new (shorter, focussed) guides. We aim for a 20% increase in access to the other Guides as our success measure.
  • Some guides will be in different forms - video-based vs text - we'll also use the analytics to determine which formats are more successful than others. This will be presented as a graph also; simply having this breakdown will indicate success to us, we can use that information to decide future documentation styles to prefer.