cotonti.com : Cotonti documentation plan https://www.cotonti.com Laatste forum onderwerpen Cotonti en Wed, 24 Dec 2025 17:32:29 -0000 milleja46 Well just some of the stuff that would be building blocks for making a theme using the variables and maybe some other useful ones for going a step further. That would be nice at least for now...

]]> Ma, 28 Jan 2013 13:29:30 -0000 Trustmaster So, it's the "Global variable reference" you vote for. Really nice choice and shouldn't be too hard to describe if considering only the essentials.

What would the "codex" consist of?

]]> Ma, 28 Jan 2013 12:42:00 -0000 milleja46 Well I only mentioned something because it seemed like the topic hadn't really been updated in so long. As well I think there needs to just be more clarification theme building specifically the different tags that can be used and everything without having to debug a page just to find it. As well 3.5.1 sounds like a good one to get done as well...Coming from wp there more or less needs to be something like their "codex" because that helped me a lot when I ran into trouble trying to write a theme(though I don't think I'll be going back to wp just because of some of the stuff I saw that went on behind the scenes with writing that software). But some kind of codex even if it just contains the essentials at the moment would be great ;)

]]> Ma, 28 Jan 2013 11:59:29 -0000 Trustmaster The plan has not been abandoned, but I personally have a problem of prioritizing with it. I can write docs from times to times but there are so many topics to cover that it's hard to focus on something.

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.

]]> Ma, 28 Jan 2013 09:54:01 -0000 milleja46 Any news on this? Looks like it kinda fell by the wayside, and the plans are great if they could get accomplished. Don't know how much help I could be since I'm kinda a newb to the system. But it would be great to see if there might be some work on this again since I know that can ruin someone's decision to go with a system if their docs are not complete to some extent.

]]> Zo, 27 Jan 2013 19:30:28 -0000 Trustmaster I just forgot about it :) I'll add i18n support to TOC later.

]]> Za, 30 Jun 2012 16:45:52 -0000 GHengeveld Lets focus on getting proper documentation in English first, then we can worry about supporting i18n.

]]> Za, 30 Jun 2012 15:56:55 -0000 Dayver #34809 Trustmaster:

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

But why without i18n ?

]]> Za, 30 Jun 2012 13:34:14 -0000 Eugene GREAT!!!

]]> Thu, 28 Jun 2012 08:54:12 -0000 Twiebie Indeed a lot easier to browse now, nice one!

]]> Wo, 27 Jun 2012 14:35:48 -0000 Trustmaster Documentation section now has interactive Table of Contents, so it is easier to browse.

]]> Wo, 27 Jun 2012 11:20:06 -0000 elfrenazo seeker. yes, think of searching more coherent example, search for "msn messenger" see results example, search for "msn messenger 7837482130" absence of any results. ¿integrated spider?

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

]]> Ma, 04 Jun 2012 01:20:47 -0000 Trustmaster I've updated the plan status but I didn't put direct links in there.

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.

]]> Vr, 24 Feb 2012 14:22:59 -0000 Macik Great idea, GHengeveld! It's a "must have" item for all user friendly CMS.

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.

]]> Zo, 25 Dec 2011 21:44:57 -0000 Trustmaster I have uploaded current trunk reference generated with PHPDoc here: http://www.cotonti.com/reference/

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.

]]> Wo, 30 Mrt 2011 20:16:06 -0000 Dyllon i've been working on a video tutorial for creating plugins, whenever the section is finished i'll surely put it in there.

]]> Za, 26 Mrt 2011 11:58:05 -0000 GHengeveld I've also marked items which are assigned red.]]> Zo, 20 Feb 2011 19:50:55 -0000 Trustmaster already completed for Siena and those which are currently in progress or need updating for Siena, with article author specified in braces. If somebody starts writing an article due to the plan, let us know and we will indicate it there. Modification proposals for the plan are still accepted.

I currently save my articles as local ODT files, I plan to add them later after this site migrates to Siena as it will use HTML markup.]]> Zo, 20 Feb 2011 17:35:20 -0000 GHengeveld Di, 09 Nov 2010 05:34:06 -0000 MIHDev I agree we need the key articles planned first.
I can contribute on the Modules and Plugins, Installation and a new multi-site installation document.
I have freed up some more of my time to work on Cotonti documentation so feel free to let me know what you require and I will endeavour to get started on it.
Regards]]> Ma, 08 Nov 2010 19:04:44 -0000 Trustmaster
  • File and Directory Structure (3.1?)
  • Modules and Plugins Explained (2)

So we should include the key articles into the plan too and then use some indication for the task assignee and progress.]]> Thu, 21 Okt 2010 21:43:43 -0000 GHengeveld Added 2 chapters:
- Global variable reference
- Resource strings reference

Also changed the point about tutorials:
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.]]> Thu, 21 Okt 2010 19:02:27 -0000 MIHDev
I think increasing the propogation of the system is vital for its continuing development and success so I will be backing you all the way on these endeavours.

Regards

CCCDev]]> Thu, 21 Okt 2010 18:56:56 -0000 Trustmaster Thu, 21 Okt 2010 16:28:27 -0000 GHengeveld
As to your point about scrolling, for a manual it's better to scroll and read on, than to click links all the time, waiting for the pages to load while hoping to find what you need when it does. After all you will not know if the page you're going to will actually contain the information you need. If its a single page you can just 'scan' the page quickly and be done with it, or use Ctrl-F to look for a specific topic.

I basically have three goals for the documentation:
  • 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
]]> Thu, 21 Okt 2010 05:44:08 -0000 MIHDev
I think that currently the documentation is good but could be tweaked and re-ordered for simplicity as outlined in your post.

Some of the sections in Config.php for example are documented but not documented if you know what I mean.

Lets take an example:

I had a requirement to develop a multi-site system on a single database using failover redundancy with shared users but not pages etc..

From my prior experience with LDU and Seditio I knew this could be done easily but was an area that while posts existed for how to kind of achieve it, nothing actually told anybody how it was achievable by a non-developer user unless I missed this.

Taking this into account I set about re-working the SQL scripts, tables and config files to do what I required. As a full-time software developer this was not an issue as I understand MySQL and programmatic structuring, it worked first time with a few tweaks but ideally it should be documented in an easy to understand 'official' way as it is a 'selling' point for the system for enterprises and corporate service providers even though it is open source.

Koradhil the ideas you mention above are superb,

one topic for discussion at the moment:
One long page is better than multiple short pages
- Could this be article specific as from experience with my clients alot of people do not have large monitors and hate scrolling. We may find that some articles are suited to multiple-documents eg: You can do Step 1 but Step 2 is optional thus contained in a separate document. This avoids scaring the user with an enormous amount of information which may not be pertinent to their requirement.
Lets make it happen :)

Regards

CCCDev]]> Thu, 21 Okt 2010 03:09:53 -0000 GHengeveld 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
]]> Ma, 11 Okt 2010 01:11:32 -0000