What would the "codex" consist of?

If people pointed to me 3-5 topics that they want most of all it would help to get them covered sooner.

There is also a temporary pause on User and Administrator docs because we plan changing both default user and admin themes in the package soon, so the screenshots would be out of date.

Documentation section now has interactive Table of Contents, so it is easier to browse.

But why without i18n ?

cotonti minimize and focus on content, excellent idea. Each content titles and descriptions own goals, and avoid duplicate.

I totally forgot it.
I'll check what I can do.

As the poll shows, the most requested section is 2.3.

Section 1.2 feels quite empty currently too, user-contributed articles and screencasts there would help a lot.

I can write some stuff for 2.2 if I know what the important topics to cover are.

Added 3 months later:

#34549 GHengeveld: 

About the documentation section, I have some thoughts on that.

• The docs should be written like a book, with a list of chapters in the sidebar so it's easy to navigate from one section to another.
• Pages should be written in a text-to-html markup language to prevent a huge mess of inconsistent html markup. My preference is Markdown. BBcode is acceptable, but not really suitable for long articles.
• The design should be minimalistic so it's easy to focus on the main content. This means the docs section should not have a header, only the topbar.
• Comments on the docs should be actively monitored and moderated. Also it should be encouraged to comment on articles so we can improve them.
• The site search should be improved or replaced with a proper crawler-based search engine such as Sphider. Also, the docs should have a dedicated search field, preferably in the sidebar.

Many of these features are possible with the existing Cotonti functionality and the plugins I wrote for this purpose (autotoc, combilists and pagesiblings).

Some good examples of docs are here, here and here.

Markdown is better for docs indeed. Though, existing entries should be kept in HTML or it will be a lot of work converting.

I'm not so sure about disabling header and footer though. I'd keep them so the site looks solid and you'd be able to get anywhere from docs.

Yeah, we need something to monitor comments on site and I think for comments lastcommentsa plugin would be enough. But we also need something to log and monitor page edits if we want the docs section to be more wiki-like.

Site search needs improvement, yes. The Find module is a great thing by design but search results are often not what you expect to see. Sphinder seems to be discontinued. I'd prefer building a Sphinx-based search module. We're on a VPS, so we can afford installing it here.

So, is there any progress in this work?

I saw several new «how-to» and «tutorial» last time. Some of it can be included in this documentation (HOWTO Maintain your Cotonti site with Git as 3.2.3, Content parser and editor management as 1.2.7). and so on.

Can you update entire plan with actual states of writing and with direct links to completed parts if it uploaded to site.

Thank you.

Added 4 days later:

Started applying new document structure and uploaded some documents which we've made so far.

Added 3 days later:

Regenerated reference with phpDoctor.

• File and Directory Structure (3.1?)
• Modules and Plugins Explained (2)

• Increase number of Cotonti developers, which hopefully means more 3rd party extensions
• Increase attractiveness of Cotonti to newcomers (novice and professional)
• Reduce number of support questions in forums

One long page is better than multiple short pages

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

$t = new XTemplate(‘path/to/skinfile.tpl’);

$t = new XTemplate(sed_skinfile('pluginname', true));

$t -> assign();

$t -> assign(“SINGLE_TAG”, ‘<p>Piece of HTML</p>’);
$t -> assign(array(
	“TAG_ONE” => ‘<p>Piece of HTML</p>’, 
	“TAG_TWO” => $somevariable
));

while($row = sed_sql_fetcharray($sql))
{
	$t -> assign(array(
		“PAGE_ROW_ID” => $row[‘page_id’],
		“PAGE_ROW_TITLE” => $row[‘page_title’]
	));
}

$t -> parse();

<!-- BEGIN: BLOCK_CODE -->
...
<!-- END: BLOCK_CODE -->

while($row = sed_sql_fetcharray($sql))
{
	$t -> assign(array(
		“PAGE_ROW_ID” => $row[‘page_id’],
		“PAGE_ROW_TITLE” => $row[‘page_title’]
	));
	$t -> parse(“MAIN.PAGE_ROW”);
}

<!-- BEGIN: MAIN -->
	<h1>{SINGLE_TAG}</h1>

	<!-- BEGIN: PAGE_ROW -->
	<p>{PAGE_ROW_TITLE}</p>
	<!-- END: PAGE_ROW -->
<!-- END: MAIN -->

$t -> parse(“ALTERNATIVE”);

1. Default files/folders
2. Using and understanding hooks
3. Using the XTemplate system, defining tags and using rows
4. Setting config values and using them
5. Writing localisations and using $L / {PHP.L}

• be unique
• be all lowercase
• consist of only letters, numbers and dashes (-)

<?PHP

/* ====================
[BEGIN_SED_EXTPLUGIN]
Code=pluginname
Part=main
File=pluginname
Hooks=standalone
Tags=
Order=10
[END_SED_EXTPLUGIN]
==================== */

/**
 * Plugin description
 *
 * @package Plugin name
 * @version 1.0
 * @author You
 * @copyright Your company
 * @license BSD
 */

defined('SED_CODE') or die("Wrong URL.");

// Your plugin code

?>

$extp = sed_getextplugins('index.main');
if (is_array($extp))
	{ foreach($extp as $k => $pl) { include_once($cfg['plugins_dir'].'/'.$pl['pl_code'].'/'.$pl['pl_file'].'.php'); } }