The CakePHP 1.2 is in good shape and 1.2 docs has gone online. and
here is my 2 cents.
In recent exploration of making a good user documentation for my own
project, I have found documentation is lightweight markup, let's say
Markdown is extremely useful.
User documentation is a expensive, resource consuming task. It takes
not only the writing skill but also deep knowledge of the software
library. Docs authoring and compiling of current CakePHP 1.2
documentation data is stored in XML.
I just started using Markdown as the documentation mark up, and all
stored in source control. It makes life easier for both author, reader
and up to date of the docs.
For example:
All user docs exist in source distribution of CakePHP
File structure
/cakephp
/app
/cake
/docs
/index.php
/index.html
/controller.txt
/model.txt
/view.txt
/authentication.txt
a sample model.txt
`````````````````````````````````````````````````
Database Relationship Model
===========================
It is blah blah blah..
What is a model?
-----------------
A model is part of MVC architecture. .... etc.
section 2
-----------------
...
```````````````````````````````````````````````````````
As you can see, using lightweight markup work really well in a
development environment.
It makes developers/user life easier since it is available with the
library in text format , so its easy to
* read
* modify and submit a diff
* encourage community contribution and speed up documentation, its
far easier to write something and send a diff to CakePHP trac.
* possibly compile their own version of documentation
* parse documentation into multiple formats, let's say a chm
integrate into a IDE
* With a plugin for Trac, all documentation can be displayed inside
trac wiki.
* Using a mark up open specification which lots of tools and library
around it in multiple platform and languages.
So far its working really well for many frameworks and software
library. django, symfony, and mootools
for example django uses reStructredText
http://code.djangoproject.com/svn/django/trunk/docs/
Most interestingly, mootools even throw in a javascript Markdown
parser in the docs folder, what you get is a always up to date version
of documentation can be view in a browser with no compiling and always
up to date.
http://svn.mootools.net/trunk/Docs/
To see the mootools documentation in action just checkout to svn and
double click, and that is cool
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Cake
PHP" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/cake-php?hl=en
-~----------~----~----~----~------~----~------~--~---
