C5 Code & Documentation
Permalink
Looking at the Form - and other - blocks, the code really needs clean up, better formatting and organizing.
For example, the controller file for the form block has 747 lines, of which 370 is a class related to the block, that it better put in a separate file.
So, if I need to override the block's functionality, I need to copy all these lines just to modify a few (correct me if I'm wrong).
Also, many classes/methods/properties don't have the least amount of help text (phpdoc) to tell the kind of variable to be passed, or what a method/function does. Look at the API documentation and you'll see what I mean.
My suggestion is to have a plan on how this can be solved with the help of developers in the forum. If needed, once done and submitted, a core developer can review and commit the changes.
Awaiting your thoughts and suggestions...
For example, the controller file for the form block has 747 lines, of which 370 is a class related to the block, that it better put in a separate file.
So, if I need to override the block's functionality, I need to copy all these lines just to modify a few (correct me if I'm wrong).
Also, many classes/methods/properties don't have the least amount of help text (phpdoc) to tell the kind of variable to be passed, or what a method/function does. Look at the API documentation and you'll see what I mean.
My suggestion is to have a plan on how this can be solved with the help of developers in the forum. If needed, once done and submitted, a core developer can review and commit the changes.
Awaiting your thoughts and suggestions...
I agree the API docs suck.
What we decided we needed to do (and haven't yet) is stop generating the API docs automatically. You just don't get any value out of that, and things don't change that much in concrete5 these days.. We want to make a nicely designed API section with a jump nav and whatnot.. ala expressionEngine.
I don't agree that a wiki will solve this problem. Its not a content management issue we have here, its a content creation problem.
What we decided we needed to do (and haven't yet) is stop generating the API docs automatically. You just don't get any value out of that, and things don't change that much in concrete5 these days.. We want to make a nicely designed API section with a jump nav and whatnot.. ala expressionEngine.
I don't agree that a wiki will solve this problem. Its not a content management issue we have here, its a content creation problem.
I wouldn't prefer writing manual documentation now as it needs time and resources.
I'm talking about adding the phpdoc comments to give the developer a good explanatory text of the:
1. Class, function, object .. etc description.
2. What input is expected with type of input (string, array, object, class.. etc)
3. What output will be returned
4. Maybe a simple example (code snippet) of how it could be used.
That's it! Simple and straight forward.
Not sure if the code documentation tags used with PHPDOC could be useful to generate documentation in other tools, but it's good as a start.
The manual herehttp://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tu... is a good reference for this, and I'm one volunteer to start the work immediately.
I'm talking about adding the phpdoc comments to give the developer a good explanatory text of the:
1. Class, function, object .. etc description.
2. What input is expected with type of input (string, array, object, class.. etc)
3. What output will be returned
4. Maybe a simple example (code snippet) of how it could be used.
That's it! Simple and straight forward.
Not sure if the code documentation tags used with PHPDOC could be useful to generate documentation in other tools, but it's good as a start.
The manual herehttp://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tu... is a good reference for this, and I'm one volunteer to start the work immediately.
I know it's more effort but the community is getting bigger and some people would help you to create a better documentation.
I love wikis but not for an API documentation. Too many people have completely different ideas, it would end up being a mess I think..
Adding some more comments in the code would definitely be nice. Sometimes the sourcecode is the best documentation and having some comments there would be helpful and would have helped me in the past.
The developer documentation is something different imho. I always liked the CodeIgniter documentation a lot:http://codeigniter.com/user_guide/...
A part where common tasks are described, some major classes (Page, Collection etc.) and a documentation of all the helpers (Image helper, getThumbnail etc.)
Someone would probably have to create the structure first, otherwise it would be mess as well. But afterwards the community could add some examples. In the documentation but also in the comments (see php.net)
I love wikis but not for an API documentation. Too many people have completely different ideas, it would end up being a mess I think..
Adding some more comments in the code would definitely be nice. Sometimes the sourcecode is the best documentation and having some comments there would be helpful and would have helped me in the past.
The developer documentation is something different imho. I always liked the CodeIgniter documentation a lot:http://codeigniter.com/user_guide/...
A part where common tasks are described, some major classes (Page, Collection etc.) and a documentation of all the helpers (Image helper, getThumbnail etc.)
Someone would probably have to create the structure first, otherwise it would be mess as well. But afterwards the community could add some examples. In the documentation but also in the comments (see php.net)
I agree, in time more people are participating and I see many developers are available and willing to participate in this.
We could discuss this on IRC if needed, but we need to have a plan and start ASAP.
A quick plan of how we could start working on this is:
1. Assign code areas to be documented to a contributor.
2. Start work and commit to a developer branch of C5 SVN.
3. Review the changes and commit it if OK.
We could discuss this on IRC if needed, but we need to have a plan and start ASAP.
A quick plan of how we could start working on this is:
1. Assign code areas to be documented to a contributor.
2. Start work and commit to a developer branch of C5 SVN.
3. Review the changes and commit it if OK.
I think we should go with a wiki, as it can be updated by anyone at anytime,
If anyone has ever heard of Alliedmods they are an opensource project for VALVe games,
they have a wiki here:http://wiki.alliedmods.net/Main_Page...
that works wonders for the devs as there is an ENORMOUS Api atleast 10 times bigger than concrete5.
iv also found that people try to hack wikis a lot less as whats the point... plus no validation etc.
I vote for Wiki
Mike
If anyone has ever heard of Alliedmods they are an opensource project for VALVe games,
they have a wiki here:http://wiki.alliedmods.net/Main_Page...
that works wonders for the devs as there is an ENORMOUS Api atleast 10 times bigger than concrete5.
iv also found that people try to hack wikis a lot less as whats the point... plus no validation etc.
I vote for Wiki
Mike
It's not about hacking wikis.
It's about not having a common plan/structure.
Whether you enter the content in a wiki or a c5 page doesn't matter a lot to me. It's about a "manager" who creates the structure and tries to define a common ground for the project.
Having 10 developers working on a c5 api doc doesn't end up being a great piece of work, especially if all of us have different ideas.
We already have different views in this thread.. Some want api doc, some real manuals, some like codeigniter, some wikis...
+1 vote for a project manager
It's about not having a common plan/structure.
Whether you enter the content in a wiki or a c5 page doesn't matter a lot to me. It's about a "manager" who creates the structure and tries to define a common ground for the project.
Having 10 developers working on a c5 api doc doesn't end up being a great piece of work, especially if all of us have different ideas.
We already have different views in this thread.. Some want api doc, some real manuals, some like codeigniter, some wikis...
+1 vote for a project manager
do you seriously like this wiki:
http://wiki.alliedmods.net/Main_Page...
?
I find it a huge mess. No clue where to start, not able to understand who they wanted to create the doc structure.. You might find all the information you need if you have worked with it for a while but as a start it's nothing I would like to have for c5.
Have you ever checked CodeIgniter?
http://codeigniter.com/user_guide/...
Once you've found the "TOC-Button" at the top of the page you know where to go. You never have to click 5 times to get to the right page. There's a toc and one click and you have all the information you need.
Isn't that a lot more beautiful?
This kind of doc with a comment feature where all of us could add some more example would be a equally powerful and a lot easier to use in my opinion.
http://wiki.alliedmods.net/Main_Page...
?
I find it a huge mess. No clue where to start, not able to understand who they wanted to create the doc structure.. You might find all the information you need if you have worked with it for a while but as a start it's nothing I would like to have for c5.
Have you ever checked CodeIgniter?
http://codeigniter.com/user_guide/...
Once you've found the "TOC-Button" at the top of the page you know where to go. You never have to click 5 times to get to the right page. There's a toc and one click and you have all the information you need.
Isn't that a lot more beautiful?
This kind of doc with a comment feature where all of us could add some more example would be a equally powerful and a lot easier to use in my opinion.
+1 for a project manager from me too.
I agree with you, and I hate Wikis and never used them by the way. I know Wikipedia is the world's largest and most accurate, but I still hate wikis.
If you know a way on how we can start, maybe defining the guidelines to write the documentation I'll be very glad to start right away.
Please, let's start!
I agree with you, and I hate Wikis and never used them by the way. I know Wikipedia is the world's largest and most accurate, but I still hate wikis.
If you know a way on how we can start, maybe defining the guidelines to write the documentation I'll be very glad to start right away.
Please, let's start!
How about +10 for more content creation and less policy?
I asked who wanted to be in a group to add FAQ's and have had zero responses.
Here's another idea, it'd be awfully nice to have a list of all the custom attributes you can set to do funky stuff. We've totally spaced writing that down anywhere but version releases at most.. A nice cheat sheet with the name, handle, and what it does would be awesome.
Seriously, drown me in good content like you guys have with marketplace add-ons, and we'll figure out a better solution to the organization/management of it - just as we're testing with the marketplace now.
-frz
I asked who wanted to be in a group to add FAQ's and have had zero responses.
Here's another idea, it'd be awfully nice to have a list of all the custom attributes you can set to do funky stuff. We've totally spaced writing that down anywhere but version releases at most.. A nice cheat sheet with the name, handle, and what it does would be awesome.
Seriously, drown me in good content like you guys have with marketplace add-ons, and we'll figure out a better solution to the organization/management of it - just as we're testing with the marketplace now.
-frz
.. the FAQ section and I'll work on it.
One thing I think of now is to add answers to many questions that are answered, and things I've experienced to share the knowledge.
Other than this, simply add the question and make it TBD and I'll work on it.
Talk the talk.. walk the walk.. ;)
One thing I think of now is to add answers to many questions that are answered, and things I've experienced to share the knowledge.
Other than this, simply add the question and make it TBD and I'll work on it.
Talk the talk.. walk the walk.. ;)
yer in.
You should be able to add pages of the FAQ type under
http://www.concrete5.org/help/faq/...
Take a look at any of the ones towards the end of the list for best practice.
I don't really have a list of TBD questions or I'd just answer them myself. ;) What I have found works is if you're answering a question you've answered in the forums before, just jump over to the FAQ section and make the page there and link to it instead of posting again from scratch.
Painful, but again documentation isn't tools, its legwork. ;-\
You should be able to add pages of the FAQ type under
http://www.concrete5.org/help/faq/...
Take a look at any of the ones towards the end of the list for best practice.
I don't really have a list of TBD questions or I'd just answer them myself. ;) What I have found works is if you're answering a question you've answered in the forums before, just jump over to the FAQ section and make the page there and link to it instead of posting again from scratch.
Painful, but again documentation isn't tools, its legwork. ;-\
some expansion of how to use the functions would be very helpful.
A wiki page would be perfect for this type of living doc imo.