Community Contributors Invited to Update Percona Monitoring and Management Documentation
Percona is making changes in its documentation processes for Percona Monitoring and Management (PMM) to make it easier and more welcoming for community members to contribute to our documentation.
Percona Monitoring and Management (PMM) is a free, open-source database monitoring tool. It ‘mind-melds’ with your MySQL, MongoDB, or PostgreSQL servers and tells you what’s going on inside; what queries are draining resources, and why.
PMM’s technical documentation is good. But, with your help, we want to make it better. Here’s what we’ve got planned for it.
- a move from reStructuredText to Markdown, making it easier for anyone to contribute;
- a complete reorganization of sections, to make them more logical and consistent;
- more ways to navigate the documentation (search, content maps, topic directories);
- more examples and screenshots better suited to your use-cases;
- regular ‘test-drives’ of our documentation, to make sure it’s technically correct and up-to-date;
- more visual elements, to help you understand and navigate the content;
- a (gradual) rewording and reformatting of everything, to make it easier (and, who knows? more fun) to read.
The PMM team writes great software, but we don’t use it the way you do.
We want PMM’s documentation to be as open as its code, and to encourage contributions to improve the quality and usability of the information. In effect, we want all our users to be PMM technical writers. (It’s one of the motivations for moving to Markdown: to encourage more community contributions.)
To see for yourselves, take a look at our PMM Documentation GitHub repository, or click the Edit this page link anywhere in the PMM2 documentation site to jump to the Markdown source file for that page. (But you can still use Jira to suggest changes or improvements.)
What Will Change?
The PMM technical documentation website is static HTML created by Sphinx and reStructuredText. These are great tools for technical writers, less so for developers and users.
We converted our documentation to Markdown because it’s a cleaner syntax, it’s easier to learn, and the files look good when seen in GitHub. There’s also a wider variety of tools for converting Markdown into HTML.
Behind the scenes, we’ll switch to using MkDocs to convert the Markdown files into HTML. At first, the new site will have the same look and feel, the same section names, and the same page URLs.
Rest assured, the content stays the same! (At least for now.)
There will be some subtle changes to the navigation bars—MkDocs treats sections differently—but only the most loyal, avid and eagle-eyed readers should notice.
We’ll try to preserve your favorite bookmarks, and help you reorient yourself to the new section layout when it comes. But some links will change—the web wasn’t written in stone.
The documentation for PMM 2 evolved from that for PMM 1. Its structure (the sections and their order) has grown organically over time, not always in the most logical way.
What’s we have now is not the best way to explain PMM 2 and its potential, nor will it accommodate the new exciting product features coming down the line.
We’re working on changes. (We’d love your help.)
by Paul Jacobs via Percona Database Performance Blog