Cotonti / Open Source PHP Content Management FrameworkContent Management Framework

Forums / Cotonti / Documentation / Cotonti documentation plan

Plans for improving the Cotonti documentation

#33257 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, 8 years ago)