Форуми / Cotonti / Documentation / Cotonti documentation plan

As one of my primary tasks as Administrator, I'm going to be working on improving the documentation area. This topic will be used to write and discuss the documentation plan (which will be the reference for the changes we're going to make. Please leave any suggestions you may have in this topic.
 

Cotonti documentation plan (draft)

• New category structure: categories and pages are numbered in order to make 'chapters'
• Documentation root is an index page listing all categories and their underlying pages
• Multi-language is implemented as alternative pages, meaning an English version is always required first
• Pages are laid out in a consistent way, using headers and code examples where appropriate
• One long page is better than multiple short pages
• Option to download a page (chapter) as PDF
• Tutorial-style documentation can be used when appropriate, for the Installation chapter for example. More specific/niche tutorials get their own listing and could be posted in the Cotonti.com 2.0 blog.
• Provide explanation for multiple platforms (Windows/Linux)
• Include some documentation in Cotonti itself (Admin Help)

Chapters

1. Manual
   1. Getting started
      1. Requirements (GHengeveld)
      2. Installation (GHengeveld)
      3. Upgrading (Trustmaster)
      4. Initial setup and configuration (GHengeveld)
   2. Administration
      1. Dashboard
      2. Configuration
      3. Users & Rights
      4. Structure & Pages
      5. Extra fields
      6. Extensions
      7. Tools, trash & misc.
      8. Content parser and editor management (Trustmaster)
      9. Extension updates (Trustmaster)
      10. SEF URLs (Trustmaster)
      11. Maintain your site with Git (Trustmaster)
2. Extending Cotonti
   1. Directory structure (Trustmaster)
   2. Extensions
      1. Introduction to extension development (GHengeveld)
      2. Configuration values (GHengeveld)
      3. Hooks (Trustmaster)
      4. Converting Genoa plugins to Siena (Trustmaster)
      5. Advanced plugin development tutorial (Trustmaster)
      6. XTemplate for programmers (GHengeveld)
   3. Themes
      1. Overview of Cotonti Themes (musiconly)
      2. CoTemplate Introduction (musiconly)
      3. Advanced CoTemplate for Designers (GHengeveld)
      4. Custom themes for Administration panel (Trustmaster)
      5. How to list available tags and blocks in CoTemplate (Trustmaster) 
      6. CoTemplate statements reference (Trustmaster)
      7. Tutorial: HTML template into Cotonti Theme (Kort)
   4. Localizations
      1. Localization files for Cotonti (Pieter)
      2. Updating localizations (Steffen)
3. Developer Guide
   1. General development information
      1. Technical concepts (Trustmaster)
      2. Coding guide & style (Trustmaster)
   2. Debugging and testing
      1. Debug helpers API (Trustmaster)
      2. Using XDebug with NetBeans
   3. API reference
      1. Cotonti Code reference (PHPDocumentor)
      2. AJAX helpers (Trustmaster)
      3. Authorization API
      4. Cache subsystem (Trustmaster)
      5. Configuration API
      6. Database layer
      7. Extensions API
      8. ExtraFields
      9. Forms API (Trustmaster)
      10. Messages, error handling and validation (Trustmaster)
      11. Understanding resource strings (Trustmaster)
      12. Uploading files
   4. Hooks
   5. Global variable reference
   6. CoTemplate
      1. Standard tags reference
4. Quick help
   1. Troubleshooting FAQ
   2. Code snippets
5. Modules
   1. (list modules)
6. Plugins
   1. (list plugins)

Assigned
In progress
Completed
 

Documentation style

Article layout

1. Introduction
2. General implications (basic)
3. Advanced topics
4. Exceptional cases
5. Conclusion

Styling

Headings

• Start at H2 (H1 is reserved for article title)
• Don't skip headings

Code blocks

• Single lines: preformatted text
• Multiple lines: code block for specific language
• Force line end: 80 characters