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.

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.

Participants

Writer:


Arzoo

Volunteers:


Apurva Bhide , Christian Horn and Nathan Scott

We have a strong technical writing candidate for the project who was our writer from Google Season of Docs last year and is interested in working on another major project. We have a proven, successful relationship that we are keen to continue to build on.

This project expands on the readthedocs documentation that was produced last year, so we anticipate rapid results as our writer is already very familiar with PCP and Grafana.

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

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.

Project budget

Budget Item Item Amount Running Total Notes
Technical writer stipend $5000 $5000
Volunteer stipend $1500 $6500 x3 volunteers @$500
Swag $200 $6700 x4 participants @$50 [redbubble]
Organisation donation $670 $7370 10% of total [OpenCollective]
Total: $7370

Other notes

PCP is a mature open source project, active now for well over 20 years. We have experience mentoring students and writers, participating in Google Summer of Code for 5 years, and in last years Google Season of Docs program. We had a very successfully collaboration with our writer last year which we'd love to build on further this year.

Thank you for running the Season of Docs program. Our users have benefitted immensely from it and it has allowed us to move in directions our resources would not have allowed so we're extremely grateful!