Downside of concrete5

Permalink
Concrete5 is quite good CMS, however in my opinion documentation is a mess, when you are learning it it's really ugly to find what you are looking for, because learning information is a big mess, there is no place where all functions would be organized and explained.

For example, right now I want to find what does set_block_tool function really does, tried googling, tried concrete5 search, found only one thread where this function was mentioned. But where the hell is it in documentation???

NamelessHero
 
JohntheFish replied on at Permalink Reply
JohntheFish
set_block_tool is a private function of the block controller in the Ajax Lessons addon., so you won't find it documented in the concrete5 developer documentation. It is declared in the same controller.php files as it is called from, a few lines below where you are probably reading it in the file.

In the Ajax Lessons blocks it is used as a convenience to wrap the interface to getBlockTypeToolsURL(), which you will find in the docs page and howtos.

That aside, I don't know of any developers who don't think there is a lot of room for improvement of the main documentation.
JohntheFish replied on at Permalink Reply
JohntheFish
NamelessHero replied on at Permalink Reply
NamelessHero
Oh, I was too hasty to start looking for this function, it really is declared there, thanks.

But I still think that concrete5 documentation should be rewritten, it should be written with a content like a book. With chapters describing all the different aspects in depth. Main downside is that it lacks explanation in depth, because every new concrete developer should try to understand how everything works.
goutnet replied on at Permalink Reply
Sadly, as for most open source project, the best documentation … is the code itself.

As I have been answered with a similar question in the Linux Kernel code :

"Use the source Luke, use the source!"

vim+ctags is a good help to find your way in
MrKDilkington replied on at Permalink Best Answer Reply
MrKDilkington
I agree with goutnet. You can learn a lot by going through the source code. This isn't an option for everyone though, unless you know the basics of object-oriented PHP you will be lost.

The guys at PortlandLabs control the direction of the architecture of concrete5, but it is still an open-source project. We all get to use it for free which is pretty great.

Until we get documentation, we all can pitch in and make short explanations and how-to's when we figure something out.

Documentation and community are holding back concrete5 from wider adoption. Many people weigh community activity and size heavily when choosing a open-source project.
NamelessHero replied on at Permalink Reply
NamelessHero
Yeah, it's so true, I agree too, the best way to learn concrete is by analyzing source code.
frz replied on at Permalink Reply
frz
We're setting aside some time for updating developer docs once we get the next version out the door.
There's also some folks helping on user docs now. If anyone wants to volunteer towards that effort, PM evan here.
We're also exploring a better way to output the API docs and perhaps include disqus comments in them.