Jetendo CMS Documentation System Progress

Fri, Feb 22, 2013 at 5:15PM

I just finished making a new layout and css styles for the Jetendo CMS documentation system. 

Jetendo CMS Documentation Template Example

Update 5/10/2013: The documentation system for Jetendo CMS is now fully built and there are some pages added to it:

I integrated automatic syntax highlighting from the prettify project  so code examples as easier to read.   I also redid the css/js to have a max-width of 1170 pixels - a common trend in new HD web designs.  On Internet Explorer 8 and below, it will display at 960 wide since it doesn't support all the modern HTML 5 / CSS 3 features I'm using.    The Jetendo CMS web site is not responsive & mobile friendly resizing between 1170 and 400 pixels wide so that it is easy to read on any device.  Responsive web design for documentation is very useful on a tablet because it lets you read it all like a book.  Most documentation is written like 1996 web design on purpose to make it super functional & compatible, but responsive web design helps you add more features without cluttering the page.  Quick access to features like parent section navigation links, search, and multiple version navigation improve documentation without adding much clutter.

Each page will support disqus user comments, and eventually open community wiki editing with a third party wiki editor or my own.

Using Wiki software for the documentation

I'm doing some of my own custom work on the documentation system because I found that Github wiki was too limited since you can't insert an iframe or javascript, which means you can't have comments, google analytics, embedded videos or any kind of interactivity.  I want all of those things.   I may use a wiki that I can install and customize.  The open source Java clone of Mediawiki, JamWiki, seems to be at least 3 to 5 times faster then the PHP based wiki software despite supporting the same syntax as Wikipedia (Mediawiki).   I'm sure the speed of the documentation would be acceptable with any solution, but I do prefer to focus on high performance solutions, and add more caching as I develop something further.  Having a quality docs system built with CFML will provide another use case for adopting Jetendo CMS.

Actual progress on written documentation has be made.

I wrote about 12 pages of new documentation which includes some semi-complete pages and a large outline of all pages.  In addition to 7 pages I had (around 6000 words).  I'll have to begin adding them to the actual site soon.  It's exciting to finally start having more resources come together.  It gives me a sense of accomplishment to further improve my project by adding documentation for it.  I still need to write hundreds of pages, and generate / improve function docs, but I have done some of this before.  So it's not very far from being somewhat usable.

White-space improved for code formating

I had to add custom white-space management for the CFML pages to allow white-space through on documentation pages.  The built-in Railo white-space management was deleting the tab characters, which prevented the pretty code indenting.  Removing white-space is desirable since there can sometimes be thousands of extra lines of white-space in a large file which makes it take longer to download and also makes it harder to read when debugging.

The MySQL manual inspired the documentation design

I based the look on MySQL's docs and some other docs systems.  The reason I enjoy MySQL's documentation was because of the excellent navigation features and functional formatting they provide.  MySQL manual is one of the only ones I've found that makes it effortless to switch between different software versions of the same manual page/section.   There are far too many projects where the documentation for each version is not up to date, easy to find or consistent.  An open source project is really defined by its documentation and community support.  MySQL probably built their documentation system in-house and never abandoned it, which makes it easier to manage in the long run.  I will probably have a system that is 100% mine before long, and include it as something others can use as part of Jetendo CMS itself.

See how nice the navigation for MySQL's Manual is.

The forum will also be an important source for finding Jetendo CMS information

Google groups is super awesome and a great place for new documentation issues to be discussed and discovered.  It can do discussion group / tags / categories / stick posts / locked posts / assigning posts to specific users /  moderation / iframe embedding / post via email to group or via reply or on the web/phone / mailing list / wiki editing / question & answers solution.  I wrote posts to explain how to post bugs, and that you can edit other people's posts.  This will make our small community of registered users able to develop better resources over time that are very SEO friendly.  

Anyone using a closed ticket system for their customer should consider switching to an open forum and bug tracker.   This helps the community learn about issues and solve their own problems without having to contact the developer for everything.  It can make customer services for your software become more automated and community driven.  Also consider that the emails are sent through google's servers, which avoids you from needing to manage the email reputation of your own servers.  There should be a higher inbox delivery rate.  When you consider all the features, Google Groups can rival and surpass the functionality in most forum / ticket systems and it is a free hosted solution. 

Google groups embedded iframe example:

Documentation is important step towards becoming a better programmer

Interesting article that has a old quote from Steve Jobs.  He claims finding a great programmer is way more difficult then other kinds of skilled workers.

Many people write about what is good or bad programming too.  I have read a great deal about the subject lately as I'm aspiring to have other developers care about my work and hopefully start collaborating with me on Jetendo CMS or other projects.  Documentation is part of being a better programmer.  Sometimes while describing something, I realize that something needs to be simpler when it has too many exceptions and long explanations.  It may be that by the time the documentation is done, the code will be simpler because of it.  

Do you want to have a chapter that describes all the features of a swiss army knife or do you want it to read like there is one best way to do something?  In programming, there is always a decision to balance convention vs configuration.   Recent popular open source frameworks / projects have introduced more conventions so all the bad/average programmers can be less bad by following those conventions.  It is unclear if it helps good programmers, but probably.  I don't mind moving the source code more towards conventions.   It is just quite time consuming to do so.  In time, all things are possible.

Bookmark & Share