Documentation Team Handbook Structure Proposal

For a long time our Handbook was almost completely useless for new contributors. It’s half empty and yet full of outdated information. We want to fix this. It won’t be easy and it needs much more than just a content update. It needs complete refactoring. And we need to change our perspective and treat it as one of our ongoing projects.

Refactoring progress is tracked in Trello board. This board is public and you are welcome to join, leave your comments or just follow the progress. Please note that this board is for refactoring purposes. Once we are done with it, it will be back to only team visible and used for documentation team’s work on Handbook. Contributions to the Handbook will be done through docs trac. Or at least we’ll try to use it.

In TrelloTrello Project management system using the concepts of boards and cards to organize tasks in a sane way. This is what the make.wordpress.com/marketing team uses for example: https://trello.com/b/8UGHVBu8/wp-marketing. board you can find proposed new structure and proposed changes for each page. Please take a look, think about its usability and how intuitive it is from the new contributor’s perspective and let’s discuss it on one of coming up docs meetings.

Proposed structure:

• 1. Documentation
  • 1.1. The Team
  • 1.2. About this Handbook (new page)
• 2. Get Involved
  • 2.1. Getting Started at a Contributor Day
  • 2.2. Current Docs Projects
  • 2.3. Writing tips
• 3. Codex
  • 3.1. MediaWiki Formatting
  • 3.2. Creating a New Document
  • 3.3. Contributors (new page)
• 4. HelpHub
  • 4.1. Editing Articles
  • 4.2. HelpHub Development
  • 4.3. Translating HelpHub (new page)
  • 4.4. Contributors (new page)
• 5. DevHub
  • 5.1. Contributors (new page)
• 6. Code References
  • 6.1 Code Examples
    • 6.1.1 Migrating From Codex
    • 6.1.2 Reviewing
    • 6.1.3 Contributors (new page)
  • 6.2 Inline Documentation
    • 6.2.1 Working With Trac (new page)
    • 6.2.2 Contributors (new page)
  • 6.3 Tools
• 7. Gutenberg
  • 7.1 Getting Started (new page)
  • 7.2 Contributors (new page)
• 8. Handbook (new page)
  • 8.1 Getting Started (new page)
  • 8.2 Handbooks Style and Formatting Guide
  • 8.3 Tutorial Template
  • 8.4 Contributors (new page)
• 9. Past Projects (new page)
  • 9.1. Handbooks

This marks following pages for removal:

Empty pages:

• https://make.wordpress.org/docs/handbook/developer-resources/
• https://make.wordpress.org/docs/handbook/developer-resources/code-reference/
• https://make.wordpress.org/docs/handbook/helphub/
• https://make.wordpress.org/docs/handbook/core/
• https://make.wordpress.org/docs/handbook/references/
• https://make.wordpress.org/docs/handbook/templates/
• https://make.wordpress.org/docs/handbook/tools/
• https://make.wordpress.org/docs/handbook/tutorials-and-guides/
• https://make.wordpress.org/docs/handbook/tutorials-and-guides/the-codex/getting-started/

Unclear pages:

• https://make.wordpress.org/docs/handbook/best-practice/
• https://make.wordpress.org/docs/handbook/credits/

Outdated pages:

• https://make.wordpress.org/docs/handbook/requirements/
• https://make.wordpress.org/docs/handbook/tutorials-and-guides/the-codex/creating-a-user-page/

Merged to other pages:

• https://make.wordpress.org/docs/handbook/helphub/getting-started-with-helphub/