Forums / Cotonti / Documentation / Cotonti documentation plan

12>>>

Plans for improving the Cotonti documentation

GHengeveld
#1 2010-10-11 01:11

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
This post was edited by Trustmaster (2012-09-07 18:19, 11 years ago)
MIHDev
#2 2010-10-21 03:09
Sounds great.

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
[b]Know the question and you will be far more likely to get an answer.[/b]
GHengeveld
#3 2010-10-21 05:44
My idea with longer pages is to have an 'index', with links (anchors) to every page. Each header will get an anchor attached so you can 'jump' from chapter to chapter, which also enables you to link directly to a certain part of the text. The advantage of having a longer page is that it's possible to include information that is related to the topic on the same page, so that readers are more likely to find out about stuff they didn't even know existed. Also it enables you to use your browser's search function more effectively.

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
Trustmaster
#4 2010-10-21 16:28
I agree with Koradhil about long pages vs. short pages. An article should be a complete guide to a specific topic, but not overlapping with other topics.
May the Source be with you!
MIHDev
#5 2010-10-21 18:56
Fair point :), I think the PDF idea is certainly an attractive prospect espeically for newcomers as it avoids the overhead of having to wait for pages to load.

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
[b]Know the question and you will be far more likely to get an answer.[/b]
GHengeveld
#6 2010-10-21 19:02
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.
This post was edited by Koradhil (2010-10-21 19:11, 13 years ago)
Trustmaster
#7 2010-10-21 21:43
Apart from the categories we also need to plan the essential articles which should be present and written first. I have planned these a while ago to be written for example:
  • 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.
May the Source be with you!
MIHDev
#8 2010-11-08 19:04
Hi Trustmaster,
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
[b]Know the question and you will be far more likely to get an answer.[/b]
GHengeveld
#9 2010-11-09 05:34
You could get started on writing an installation guide which uses the installer script which comes with Siena. I think you should get Siena from the trunk and install that. All documentation has to be Siena-oriented.
Trustmaster
#10 2011-02-20 17:35
I have extended the plan up to individual articles and have marked there articles which are 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.
May the Source be with you!
GHengeveld
#11 2011-02-20 19:50
I've merged modules and plugins development into extension development, since they are very similar.
I've also marked items which are assigned red.
This post was edited by Koradhil (2011-02-20 19:58, 13 years ago)
Dyllon
#12 2011-03-26 11:58

i've been working on a video tutorial for creating plugins, whenever the section is finished i'll surely put it in there.

We are what we repeatedly do. Excellence then, is not an act, but a habit.
This post was edited by Dyllon (2011-03-26 13:45, 12 years ago)
Trustmaster
#13 2011-03-30 20:16

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.

May the Source be with you!
This post was edited by Trustmaster (2011-04-07 08:28, 12 years ago)
Macik
#14 2011-12-25 21:44

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.

https://github.com/macik
правильный хостинг — https://goo.gl/fjCa1F
Trustmaster
#15 2012-02-24 14:22

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 herehere 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.

May the Source be with you!
This post was edited by Trustmaster (2012-06-03 14:05, 11 years ago)

12>>>