Manual:Process

From Askmonty.org

About

This page describes the process for creating new documentation and adding it to the manual.

Adding New Documentation

For the purposes of this process, "item" refers to "something that needs to be documented". "Developer" refers to the single developer or team of developers that are responsible for an "item".

The process is as follows:

1. The developer identifies an item that needs to be documented.
   • This must happen at the latest when the code is pushed, but could have happened already earlier.
2. The developer either blogs about the item or gathers together what they know about the item.
   • When we include patches from other places, like Percona or MySQL forge, the contributor may already have written documentation for it. Please ask him for rights to the documentation at the same time with the patch.
3. The developer sends the link to their blog post and/or other information they have on the item to the docs team (d o c s /at/ askmonty /dot/ org). Useful information to send includes:
   • what tree on launchpad has the code for the item
   • sample queries
   • syntax definition or syntax changes for the item (if any)
4. The docs team adds the item to the docs queue.
5. The docs team 'tries out' the item. Steps for trying out the item include:
   • branching the code from launchpad
   • compiling MariaDB with the item
   • using the item (guidance from the developer, including sample queries, may be needed)
   • gathering output examples
6. The docs team writes a first draft of documentation on the item and sends it to the developer for review.
7. The developer reviews the draft and provides feedback.
8. The docs team incorporates feedback into a new draft of the documentation and sends it to the developer for review.
9. The previous two items repeat until the developer and docs team are satisfied with the documentation of the item.
10. The new documentation is added to the manual.