[Rant] Current State of Documentation
Permalink
Ok, so I need to get this off my chest.
Over the past few years, I have been woefully disappointed in the documentation for C5, specifically for developers, since 5.7. While you made commitments to fixing this nearly two years ago, not much has changed, frankly.
I am speaking as a person who wants to write packages to set up things for clients, or perhaps even eventually do something on the marketplace. Doing Web Dev is a side job for me, one of many, and I want to be able to get up and going. I love C5 at it's core, and can forgive it's slowness as the benefits are great.
However, if feels like you guys spend so much time adding new features and hacking away at things with a front-end mindset that the programmatic people are left out to hang. It was due to not having the info I needed, and literally spending hours trying to figure out pagetypes, etc, that I wrote the tutorials for those types of pages for you. It was as much reference for myself as knowing that others would be frustrated by the same things, and trying to do something about it. I even offered to the core team to do writing for them on this stuff if they would talk it over with me, but no one got back to me.
I recently spent hours trying to figure out how to see if an attribute is connected to an Express object or not (for an upgrade script), and how to add attributes once it is no longer a build object. And while I have hints, I mean seriously, why on earth are you making it so hard?!?
I honestly and earnestly believe that one of the reasons for C5 to have such a small marketplace still after the 5.7 upgrade is the fact that you have completely left developers out to hang. Unless I know the core functionality, and how the thought process is, I frankly have no clue, and you guys are really not making it easy to find out. I can't find the element/controller/helper/whatever that the express backend page uses to save the new attribute in, so I can't figure out the method. And now there are so many facades and whatever that nothing is easy to find.I am going through tons of files just trying to get a clue, which you should have given us already. Express has been out for a while. Why on earth are you not answering this? I see people asking about this basic question 6 months ago, and then someone else just days ago on the documentation site.
The core functionality NEEDS to have documentation for developers, or people are going to go to other CMS. I am already in an argument with a partner who wants to go to another CMS because C5 has such poor support in the marketplace, and because it takes him (and me) so long to find the key details we need.
You need to make it so medium level people can do things too. The simple people have the dashboard pages. The core team knows every in and out. You need to take a break, take a breath, and help out the hackers in the middle, the ones who can develop some cool marketplace ideas, and make everyone some money on it.
You have a wonderful product. But you need to do better on this. All your devs are spinning their wheels, and there are enough comments in the documentation that show a lot of people are struggling and frustrated. Give us the tools to do this if they don't exist btw. I mean actual methods, not going down so you have to know the in and out of how doctrine is being used here.
PLEASE help us. I want to give my clients great sites, and now I can with C5 with some of my data sites... but it's so much work to even get there that I don't have the hours in the day. Again, I'll happily write the content if someone just gives me a cheat sheet. But there isn't even that.
Rant over. But please help.
Over the past few years, I have been woefully disappointed in the documentation for C5, specifically for developers, since 5.7. While you made commitments to fixing this nearly two years ago, not much has changed, frankly.
I am speaking as a person who wants to write packages to set up things for clients, or perhaps even eventually do something on the marketplace. Doing Web Dev is a side job for me, one of many, and I want to be able to get up and going. I love C5 at it's core, and can forgive it's slowness as the benefits are great.
However, if feels like you guys spend so much time adding new features and hacking away at things with a front-end mindset that the programmatic people are left out to hang. It was due to not having the info I needed, and literally spending hours trying to figure out pagetypes, etc, that I wrote the tutorials for those types of pages for you. It was as much reference for myself as knowing that others would be frustrated by the same things, and trying to do something about it. I even offered to the core team to do writing for them on this stuff if they would talk it over with me, but no one got back to me.
I recently spent hours trying to figure out how to see if an attribute is connected to an Express object or not (for an upgrade script), and how to add attributes once it is no longer a build object. And while I have hints, I mean seriously, why on earth are you making it so hard?!?
I honestly and earnestly believe that one of the reasons for C5 to have such a small marketplace still after the 5.7 upgrade is the fact that you have completely left developers out to hang. Unless I know the core functionality, and how the thought process is, I frankly have no clue, and you guys are really not making it easy to find out. I can't find the element/controller/helper/whatever that the express backend page uses to save the new attribute in, so I can't figure out the method. And now there are so many facades and whatever that nothing is easy to find.I am going through tons of files just trying to get a clue, which you should have given us already. Express has been out for a while. Why on earth are you not answering this? I see people asking about this basic question 6 months ago, and then someone else just days ago on the documentation site.
The core functionality NEEDS to have documentation for developers, or people are going to go to other CMS. I am already in an argument with a partner who wants to go to another CMS because C5 has such poor support in the marketplace, and because it takes him (and me) so long to find the key details we need.
You need to make it so medium level people can do things too. The simple people have the dashboard pages. The core team knows every in and out. You need to take a break, take a breath, and help out the hackers in the middle, the ones who can develop some cool marketplace ideas, and make everyone some money on it.
You have a wonderful product. But you need to do better on this. All your devs are spinning their wheels, and there are enough comments in the documentation that show a lot of people are struggling and frustrated. Give us the tools to do this if they don't exist btw. I mean actual methods, not going down so you have to know the in and out of how doctrine is being used here.
PLEASE help us. I want to give my clients great sites, and now I can with C5 with some of my data sites... but it's so much work to even get there that I don't have the hours in the day. Again, I'll happily write the content if someone just gives me a cheat sheet. But there isn't even that.
Rant over. But please help.
Hi everyone.
I completely agree in that I am another middling developer, who in the past has loved programming Concrete5 pre 5.7 and really appreciates the time spent by other developers helping those in need. I can see that there is a lot more capability and potential in 5.8 but currently I am spending hours and hours searching around all the docs and forums to find answers. What would really help are more common use examples please.
P.s. Can't seem to access the Slack conversations, I don't have a concretecms or portlandlabs email address and can't work out how to connect from my Slack workspace.
All the best.
I completely agree in that I am another middling developer, who in the past has loved programming Concrete5 pre 5.7 and really appreciates the time spent by other developers helping those in need. I can see that there is a lot more capability and potential in 5.8 but currently I am spending hours and hours searching around all the docs and forums to find answers. What would really help are more common use examples please.
P.s. Can't seem to access the Slack conversations, I don't have a concretecms or portlandlabs email address and can't work out how to connect from my Slack workspace.
All the best.
I tend to agree more with your view of the docs than others.
It's true that at this point, although there is still plenty that would require documenting, there is also already a lot of documentation available but... it's a real mess extremely hard to navigate
As for Slack, you can register here:http://www.concrete5.org/slack
If it doesn't work, you should contact Franz Maruna, I'm sure he can help. Just be patient, he often gets pretty busy.
It's true that at this point, although there is still plenty that would require documenting, there is also already a lot of documentation available but... it's a real mess extremely hard to navigate
As for Slack, you can register here:http://www.concrete5.org/slack
If it doesn't work, you should contact Franz Maruna, I'm sure he can help. Just be patient, he often gets pretty busy.
Once again Nour, you have succinctly hit the nail on the head.
Thanks.
Thanks.
For years I've been waiting for someone to say I did something - anything - succinctly...
Thank you! :-)
Thank you! :-)
The frustration is clear in your post. I have personally written a lot of documentation for Express over the past year, but it obviously can't cover every single use case or specific concern. That's why we spent so much time and energy converting our documentation site into one that can be edited by the community. We will continue to work on the documentation and would encourage you to use slack to let us know the kinds of documentation that you really want to see.
I don't understand the complaints about us failing to appeal to developers at the expense of the front-end. We heard these complaints with updates to 5.7, but that has remained incredibly stable for the last 4 years as we've worked on developer-focused features like Express. That's what version 8 is all about. As we move into a new version of concrete5 focused on making concrete5 work well with modern JS frameworks (including a new API) this is also a developer focused feature.
I don't understand the complaints about us failing to appeal to developers at the expense of the front-end. We heard these complaints with updates to 5.7, but that has remained incredibly stable for the last 4 years as we've worked on developer-focused features like Express. That's what version 8 is all about. As we move into a new version of concrete5 focused on making concrete5 work well with modern JS frameworks (including a new API) this is also a developer focused feature.
A document has been drafted that proposes (inter alia) formation of a documentation team, and outlines tasks and processes for that team. Progress is slow because most interested parties are volunteers.
Have you found the relevant slack channels? These links MAY work:
https://concrete5.slack.com/messages/C2Q0DT1ND/...
https://concrete5.slack.com/messages/C6PM5PNN8/...