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.
In our previous Google Season of Docs project, we converted two freely-available books (the "Users and Administrators Guide" and the "Programmers Guide"), the REST API documentation, and other content into pcp.readthedocs.io .
It is this latest project we tackled the curation of a new, consistent series of focussed, task-oriented "How To" guides that assist new users in engaging immediately, by clearly showing how to solve small specific problem scenarios users encounter frequently.
The primary goal of this project was to assist first-time users to become more productive right away, while also directing traffic toward the more detailed books in close proximity to the new guides.
Initial work creating a proposal was done by the team in collaboration with Arzoo, based on guides we had in the form of email exchanges, known areas of need, as well as pre-existing guides in different formats from the main PCP website.
Once all involved agreed on the initial project content, we moved into establishing the project budget plan.
We primarily based our initial budget on funding our writer, based on previous years activities and the recommended reasonable ranges of funding from Google.
One unexpected area of difficulty was interacting with financing and shipping companies in India. After a relatively trouble-free initial payment to our writer early on, the environment around OpenCollective seemed to change for payments in India and we continue to work with them to ensure subsequent payments arrive.
Similarly, we budgeted for some swag, but trouble with shipments into India by our provider company Red Bubble meant some contributors ended up unable to receive the swag. As a result, they kindly donated their funding to the PCP project for other uses, with a plan for anyone who travels internationally for a meetup in-person to bring in swag for them, in the future when possible.
Other than these problems, the budget overall was quite appropriate and worked out well.
Several experienced community members volunteered to assist - PCP maintainers, developer and a documentation specialist. Our wonderful writer Arzoo from last years Google Season of Docs program agreed to work with us once more.
With contributors spanning only APAC countries (Australia, Japan and India), we found we were able to communicate well once more, with quick responses being in similar timezones.
Arzoo maintained an excellent timeline of deliverable items and the status of each item, throughout the project.
As observed in the time line we completed the bulk of the work we set out to achieve. The landing page for Performance Co-Pilot Quick Guides is now available and features prominently in the PCP documentation.
There were a couple of disruptions during the length of the project - laptop hardware failure and a short period of recuperation after illness. However, Arzoo was able to recover from these setbacks to complete most of the planned work - mainly we did not get into the stretch goals of the video tutorials and animated console examples).
We anticipated the new guides would provide a better suited entry point for new and inexperienced users.
Arzoo enabled Google analytics early on in the project. Since there were very few guides to start with, and with disrupted progress in the middle of the project, this is a summary of our observed traffic statistics at the end:
The project was certainly overall a success.
Going forward we need to keep an eye on the web analytics to ensure the guides are serving their purpose, as well as to help identify other possible areas needing short guides.
As we didn't complete any video or animated style tutorials we were unable to use that metric as originally planned (in order to assess if such mediums are preferred by users and whether they provde more popular than text and diagrams).
A good result for the Performance Co-Pilot project. We have a baseline set of short guides getting new users of the software able to solve problems immediately, and to learn more quickly about the wider set of PCP tools.
We introduced consistency into all Tutorials and Guides across the project, by using a single readthedocs.io landing page for all PCP guides (same location, format, look-and-feel). Each new guide we add now will be incorporated into the set we've established during this project.
In terms of what we'd do differently next time, perhaps a focus on getting video tutorials and animated console examples integrated earlier on would have helped us to get content suited to that medium using it more, instead of running out of time to explore that at the end.
We've really enjoyed working with Arzoo further improving the PCP documentation - a big thanks again to Google for running this program!
Arzoo's notes on the project from the writer's perspective .
Landing page for the new and improved PCP Quick Guides .