New Marketing Strategy for Concrete CMS
PermalinkTake your time to give me some good ones, and I'll make the time to answer them here.
Enjoyed this video and agree with Vidal Themes response. I appreciate the things you have planned to support the community in marketing concrete 5...i mean concrete CMS.
1. Providing resources to help prompt the tool to the public, why it's a good choices, why it's good for them would help people resell it. I'm working with a customer right now where i'm promoting Concrete CMS but they've never heard of it and they are concerned.
2. Documentation, Tutorials, and the like. I've been writing software for 25 years and historically have picked up new programming languages, tools, etc. really easily. However, i'm struggling like the dickens with Concrete 5. The learning curve is HUUUGGGEEE.
How-to's and tutorial's are really good...and getting rid of out-of-date info also would be helpful. I'm working under v8 and as such information on V5 doesn't help much. A lot has changed. Even the core documentation isn't right all the time. My best methods of learning are to find an existing package/product that does want i want, and learn from that.
That said, i prefer written tutorials and examples over videos.
This is not a criticism as it is a great tool and i understand it's history, this is just input.
1. Providing resources to help prompt the tool to the public, why it's a good choices, why it's good for them would help people resell it. I'm working with a customer right now where i'm promoting Concrete CMS but they've never heard of it and they are concerned.
2. Documentation, Tutorials, and the like. I've been writing software for 25 years and historically have picked up new programming languages, tools, etc. really easily. However, i'm struggling like the dickens with Concrete 5. The learning curve is HUUUGGGEEE.
How-to's and tutorial's are really good...and getting rid of out-of-date info also would be helpful. I'm working under v8 and as such information on V5 doesn't help much. A lot has changed. Even the core documentation isn't right all the time. My best methods of learning are to find an existing package/product that does want i want, and learn from that.
That said, i prefer written tutorials and examples over videos.
This is not a criticism as it is a great tool and i understand it's history, this is just input.
that makes perfect sense and I totally agree we need to step up the docs.
these are all great ideas... many of them were already central on our marketing roadmap but I'll add a couple too... thanks!
https://www.concrete5.org/about/blog/news/help-us-test-new-community-site
if you're looking for the beta signup for new community ^^^
if you're looking for the beta signup for new community ^^^
I've filled in the form about a month ago and haven't received anything: no confirmation, no link, nothing.
@linuxoid, I did this a week or so ago. There was a validation link emailed to me. Other than that, haven't heard anything either.
Thx.. Yup, I see you in there. It's coming.
I like everything mentioned in this video, the thinking to me feels very clean and realistic. The recognition that more can be done to engage agencies makes total sense to me.
I've listened to the video twice, and have given it quite a fair bit of thought from our 'web shop' point of view. Mesuva is only two devs, but we work with designers and a whole bunch of others that build concrete sites. Some of those would call themselves 'agencies', others would call themselves 'developers', but they all get in and build 'stuff'.
I know the documentation gets critiqued all the time, so I don't want to sound like I'm rehashing the same thoughts, but from listening to the video and thinking about how we've been using other frameworks and systems over the last few years, I have some specific thoughts as to how documentation fits into the future of Concrete CMS.
My realisation is that I believe documentation is the number one critical aspect to focus on to create a bigger developer and agency audience, and everything else should be seen as secondary. Perhaps that wasn't the case some years ago, but I'm pretty confident of this in 2021.
The vast majority of our clients had never heard of concrete5 before we introduced them, and now they love it. The broader audience comes from developers/agencies loving concrete5.
I know myself that when I've hunted around for libraries and other systems, if I come across documentation that looks messy or incomplete, I will naturally put that product further down my list - and often that might not be a true reflection of the product itself. I can't help but think that's commonly happening with concrete - potential new converts aren't landing on the documentation and going 'wow, it's all here, I'll get stuck in', like they do for something like Laravel.
I'll also add that it's on record that I activity will defend types of blanket criticism of the current documentation. The docs have a huge amount of well written and well thought out content, and it does cover most aspects of concrete well. I routinely use the documentation myself, and it's be essential for many of our projects where we're building complex add-ons. I also recognise that writing docs is a pain, and that Portland Labs isn't a huge company with infinite resources! Concrete is also difficult to document due to the very wide breadth of functionality and use cases, it's both a framework and an end-product, unlike others I'm mentioning that are purely frameworks.
The thoughts I have about documentation are really to do with how I as a developer engage with it on other projects, in particular Laravel, VueJs, Bref and all the PHP and Javascript libraries that we'll commonly pull in via composer or npm.
My main thoughts are about Laravel, which I'd say has a lot in common with concrete, in that it's not just a software project, it has a big (and successful) ecosystem around it, paid hosting services, commercial products, etc. When you visit laravel.com, the first menu item and the first call-to-action is 'Documentation'. It's the number one way that it engages new and existing developers, and that doco jumps immediately into how to get started.
The rest of the ecosystem to do with Laravel is easy to get to, but it's there for _after_ a developer has checked out the docs, seen how well documented it is, understood the core concepts and has jumped in.
The focus is so strong that note that the main search on laravel.com is 'Search docs', rather than search the site.
I've lost count of the number of times I've read how the documentation for Laravel is one of they key reasons it's been so heavily adopted and why it kicks ass. The docs are extensive but also concise, and are widely praised. The layout is also very clean and it just flows. I'm praising _documentation_ here of all things, it's that solid!
As it's that kind of positive engagement with doco that I think would be great for Concrete CMS, in particular on the .org side of things. Make .org for the devs that want to work with concrete to build stuff, or want to contribute its development.
As I've said, I will actively defend concrete's documentation efforts, but I will add that the current feel and structure just doesn't seem right, or at least it doesn't feel familiar like a lot of other documentation I come across.
Some rough thoughts:
- the landing page for the docs presents both the User guide and multiple links for developers, and it feels like there are multiple layers of nav to get through. It's nicely presented, and I can see the reasoning, but it's still confusing structurally, especially to a newcomer.
- the right hand side nav has always felt weird to me, so much so I mentioned it to Andrew once
- there are things like version history right in the middle of the introduction content, so I can't just read it from start to finish like I can for other projects
- the order that the documentation is presented doesn't seem to flow to me, there are menu items like 'Framework' that opens up to a large section, whereas others go straight to content.
- lots of pages open to just a paragraph of info that isn't that useful, and you then have to scroll down and pick a sub-top on the menu
Ultimately what I would love to see as a developer, and to attract other developers is:
- one URL to jump right into the documentation, the same sort of broader style as
http://laravel.com/docs/8.x or http://vuejs.org/v2/guide/ or http://bref.sh/docs/
- a familiar full width layout, with one menu on the left, and one hierarchy
- content that could effectively be exported into a singular book. You can find single file pdf/ebook files for Laravel's docs, which are great for someone to study.
- I really think doco should be written in markdown and hosted somewhere like github. Comments on doco are great for clarifications, but I can't help but feel that the output agnostic nature of markdown is the way to go.
Franz mentions about using third party systems to fill in gaps, I reckon that for documentation it would be worthwhile going down this path.
Not long ago I put together some (admittedly rough) documentation for Community Store:
https://concrete5-community-store.github.io/community_store/...
That uses http://vuepress.vuejs.org/, and now that it's set up it's incredibly easy to update and add further content to. I simply have to commit to github and the CI takes care of pushing updates. It being written in markdown makes it much easier to cut and paste stuff in, I can fix edits directly from github, it just feels _familiar_ as a developer.
I'm not saying it's amazing doco, but it sure is simple to manage, and there's only one layout to encounter as the reader.
I also used markdown for our quick start guide for v8 -
https://app.gitbook.com/@concrete5-resources/s/quick-start-guide-v8/...
The content is sitting here: https://github.com/Mesuva/concrete5-quick-start-guide-v8...
That same content can be viewed on the web, or exported to a PDF for sending to a client.
Perhaps it's what developers expect to find on a modern open source projects.
Having used concrete5 for maybe 8+ years, and having pushed it to many of its limits, building all sorts of crazy stuff with it, I couldn't be a bigger fan. The codebase is exceptional for such a large CMS, and it only continues to improve. Once a developer starts actually using it, I think they can see how good it is quickly, but I think documentation is a mental barrier first.
So to try to cut one of my typical rambles down to one sentence - my belief is that a documentation platform that can been considered in the same league as something like Laravel's is an essential goal for this new marketing energy.
We will do our best to help were we can.
I've listened to the video twice, and have given it quite a fair bit of thought from our 'web shop' point of view. Mesuva is only two devs, but we work with designers and a whole bunch of others that build concrete sites. Some of those would call themselves 'agencies', others would call themselves 'developers', but they all get in and build 'stuff'.
I know the documentation gets critiqued all the time, so I don't want to sound like I'm rehashing the same thoughts, but from listening to the video and thinking about how we've been using other frameworks and systems over the last few years, I have some specific thoughts as to how documentation fits into the future of Concrete CMS.
My realisation is that I believe documentation is the number one critical aspect to focus on to create a bigger developer and agency audience, and everything else should be seen as secondary. Perhaps that wasn't the case some years ago, but I'm pretty confident of this in 2021.
The vast majority of our clients had never heard of concrete5 before we introduced them, and now they love it. The broader audience comes from developers/agencies loving concrete5.
I know myself that when I've hunted around for libraries and other systems, if I come across documentation that looks messy or incomplete, I will naturally put that product further down my list - and often that might not be a true reflection of the product itself. I can't help but think that's commonly happening with concrete - potential new converts aren't landing on the documentation and going 'wow, it's all here, I'll get stuck in', like they do for something like Laravel.
I'll also add that it's on record that I activity will defend types of blanket criticism of the current documentation. The docs have a huge amount of well written and well thought out content, and it does cover most aspects of concrete well. I routinely use the documentation myself, and it's be essential for many of our projects where we're building complex add-ons. I also recognise that writing docs is a pain, and that Portland Labs isn't a huge company with infinite resources! Concrete is also difficult to document due to the very wide breadth of functionality and use cases, it's both a framework and an end-product, unlike others I'm mentioning that are purely frameworks.
The thoughts I have about documentation are really to do with how I as a developer engage with it on other projects, in particular Laravel, VueJs, Bref and all the PHP and Javascript libraries that we'll commonly pull in via composer or npm.
My main thoughts are about Laravel, which I'd say has a lot in common with concrete, in that it's not just a software project, it has a big (and successful) ecosystem around it, paid hosting services, commercial products, etc. When you visit laravel.com, the first menu item and the first call-to-action is 'Documentation'. It's the number one way that it engages new and existing developers, and that doco jumps immediately into how to get started.
The rest of the ecosystem to do with Laravel is easy to get to, but it's there for _after_ a developer has checked out the docs, seen how well documented it is, understood the core concepts and has jumped in.
The focus is so strong that note that the main search on laravel.com is 'Search docs', rather than search the site.
I've lost count of the number of times I've read how the documentation for Laravel is one of they key reasons it's been so heavily adopted and why it kicks ass. The docs are extensive but also concise, and are widely praised. The layout is also very clean and it just flows. I'm praising _documentation_ here of all things, it's that solid!
As it's that kind of positive engagement with doco that I think would be great for Concrete CMS, in particular on the .org side of things. Make .org for the devs that want to work with concrete to build stuff, or want to contribute its development.
As I've said, I will actively defend concrete's documentation efforts, but I will add that the current feel and structure just doesn't seem right, or at least it doesn't feel familiar like a lot of other documentation I come across.
Some rough thoughts:
- the landing page for the docs presents both the User guide and multiple links for developers, and it feels like there are multiple layers of nav to get through. It's nicely presented, and I can see the reasoning, but it's still confusing structurally, especially to a newcomer.
- the right hand side nav has always felt weird to me, so much so I mentioned it to Andrew once
- there are things like version history right in the middle of the introduction content, so I can't just read it from start to finish like I can for other projects
- the order that the documentation is presented doesn't seem to flow to me, there are menu items like 'Framework' that opens up to a large section, whereas others go straight to content.
- lots of pages open to just a paragraph of info that isn't that useful, and you then have to scroll down and pick a sub-top on the menu
Ultimately what I would love to see as a developer, and to attract other developers is:
- one URL to jump right into the documentation, the same sort of broader style as
http://laravel.com/docs/8.x or http://vuejs.org/v2/guide/ or http://bref.sh/docs/
- a familiar full width layout, with one menu on the left, and one hierarchy
- content that could effectively be exported into a singular book. You can find single file pdf/ebook files for Laravel's docs, which are great for someone to study.
- I really think doco should be written in markdown and hosted somewhere like github. Comments on doco are great for clarifications, but I can't help but feel that the output agnostic nature of markdown is the way to go.
Franz mentions about using third party systems to fill in gaps, I reckon that for documentation it would be worthwhile going down this path.
Not long ago I put together some (admittedly rough) documentation for Community Store:
https://concrete5-community-store.github.io/community_store/...
That uses http://vuepress.vuejs.org/, and now that it's set up it's incredibly easy to update and add further content to. I simply have to commit to github and the CI takes care of pushing updates. It being written in markdown makes it much easier to cut and paste stuff in, I can fix edits directly from github, it just feels _familiar_ as a developer.
I'm not saying it's amazing doco, but it sure is simple to manage, and there's only one layout to encounter as the reader.
I also used markdown for our quick start guide for v8 -
https://app.gitbook.com/@concrete5-resources/s/quick-start-guide-v8/...
The content is sitting here: https://github.com/Mesuva/concrete5-quick-start-guide-v8...
That same content can be viewed on the web, or exported to a PDF for sending to a client.
Perhaps it's what developers expect to find on a modern open source projects.
Having used concrete5 for maybe 8+ years, and having pushed it to many of its limits, building all sorts of crazy stuff with it, I couldn't be a bigger fan. The codebase is exceptional for such a large CMS, and it only continues to improve. Once a developer starts actually using it, I think they can see how good it is quickly, but I think documentation is a mental barrier first.
So to try to cut one of my typical rambles down to one sentence - my belief is that a documentation platform that can been considered in the same league as something like Laravel's is an essential goal for this new marketing energy.
We will do our best to help were we can.
+1000000 karma to @mesuva.
A suggestion I made on slack (so far back that it has fallen off the history) was that any code change / pull request should also include adding or changing associated documentation. To make documentation part of the approval requirement on code changes. Not just @docblocks for the api. Full developer docs for using it.
This will obviously have a big initial overhead because the docs need to be brought up to a state where they can be maintained through such a process.
Integration of docs updates with code updates points towards the Git based approach @mesuva describes.
A suggestion I made on slack (so far back that it has fallen off the history) was that any code change / pull request should also include adding or changing associated documentation. To make documentation part of the approval requirement on code changes. Not just @docblocks for the api. Full developer docs for using it.
This will obviously have a big initial overhead because the docs need to be brought up to a state where they can be maintained through such a process.
Integration of docs updates with code updates points towards the Git based approach @mesuva describes.
Thanks for this really thoughtful reply. I totally agree that without great documentation, there is no path to success.
I know Evan and his team will be spending significant ongoing energy in trying to turn those thumbs downs into thumbs up, and really flushing out sections that we stubbed out at one point that just clearly need more love.
One thing I've come to realize over the years of concrete being open source is the massive difference in attention types needed for product vs. services work.
The big services projects we've done to fund concrete in the past are a lot like hunting for whales. There's a lot of time and costs in finding and closing these huge projects, but once you're working on it, really only a few big things matter. Is it getting done on time? Is it being built well? Is the client happy? You find yourself facing massive important critical moments from time to time, but it's really easy to not sweat the details too much in between the big crunches.
Successfully managing a product on the other hand feels more like farming. There are fewer existential problems that you have to solve immediately, and instead there's just a lot of little things that should be done right or you're going to mess up the fall crop. When I look back at some of our sins over the years, I can't point to one and say "well that's where we dropped the ball." I do recognize that a lot of little things can add up however. It feels a bit like we started a farm, threw some seeds around and then didn't pay much more attention as we went off in the woods to hunt big game. Not shockingly, fast forward a few months and the fields look spotty.
As a bunch of engineers and "Agency Aarons" ourselves, our natural tendency is to over engineer solutions to problems before they're needed. "Why spend 2 hours doing something by hand when you could spend 2 days trying to automate it?" To keep battering this farming/hunting metaphor, in the past we might recognize that "a field needs to be watered" and so I'd go out and buy 5k of irrigation hose and connectors, spend some time futzing around with it, and then promptly go on and worry about some other problem because I had made a MVP irrigation system. Who knows if that irrigation system is actually working? The engineers in us think "hey, didn't I already solve that once??" A smart farmer would just wake up every day and hand water the crops until they really are growing well. Does he need a 5k irrigation system? Maybe, but let's do that when it really has become wildly inefficient doing the actual work, the fields are healthy, and it's an opportunity to do more instead of an excuse to do less.
This isn't to say that I don't recognize that large parts of the community site need to be rebuilt, nor do I strongly disagree with any of the suggestions above. I just want to really question investing our limited time in a solution that feels like its just focused on changing the tools rather than changing the work we do with the tools.
We spent some real time relaunching parts of the docs last summer. We added the Developers Guide which took a few weeks of Andy's time to write. We re-orged a bunch of pages. We threw a bunch of energy at it for a while, launched what we had, and left. Since then our efforts have been limited to approving other people's how-tos and thanking anyone who makes any edits during our monthly Town Hall. That's a very "hunting" type solution to the challenge.
There is no single big push of time that will result in perfect documentation we don't have to continually revise. Moving the nav from one side to the other, or even changing the tool we use to manage the content will not make the content more compelling. That's not to say the suggestions you make aren't valid, or that IA/navigations aren't important. I just really want everyone to understand we're trying to shift our energy here from the hunting engineer's perspective of "lets just make these changes so we can move on" into more of a product managers perspective of "what can I do today, and what can I do tomorrow to make what we have a bit better than what we had."
I know Evan and his team will be spending significant ongoing energy in trying to turn those thumbs downs into thumbs up, and really flushing out sections that we stubbed out at one point that just clearly need more love.
One thing I've come to realize over the years of concrete being open source is the massive difference in attention types needed for product vs. services work.
The big services projects we've done to fund concrete in the past are a lot like hunting for whales. There's a lot of time and costs in finding and closing these huge projects, but once you're working on it, really only a few big things matter. Is it getting done on time? Is it being built well? Is the client happy? You find yourself facing massive important critical moments from time to time, but it's really easy to not sweat the details too much in between the big crunches.
Successfully managing a product on the other hand feels more like farming. There are fewer existential problems that you have to solve immediately, and instead there's just a lot of little things that should be done right or you're going to mess up the fall crop. When I look back at some of our sins over the years, I can't point to one and say "well that's where we dropped the ball." I do recognize that a lot of little things can add up however. It feels a bit like we started a farm, threw some seeds around and then didn't pay much more attention as we went off in the woods to hunt big game. Not shockingly, fast forward a few months and the fields look spotty.
As a bunch of engineers and "Agency Aarons" ourselves, our natural tendency is to over engineer solutions to problems before they're needed. "Why spend 2 hours doing something by hand when you could spend 2 days trying to automate it?" To keep battering this farming/hunting metaphor, in the past we might recognize that "a field needs to be watered" and so I'd go out and buy 5k of irrigation hose and connectors, spend some time futzing around with it, and then promptly go on and worry about some other problem because I had made a MVP irrigation system. Who knows if that irrigation system is actually working? The engineers in us think "hey, didn't I already solve that once??" A smart farmer would just wake up every day and hand water the crops until they really are growing well. Does he need a 5k irrigation system? Maybe, but let's do that when it really has become wildly inefficient doing the actual work, the fields are healthy, and it's an opportunity to do more instead of an excuse to do less.
This isn't to say that I don't recognize that large parts of the community site need to be rebuilt, nor do I strongly disagree with any of the suggestions above. I just want to really question investing our limited time in a solution that feels like its just focused on changing the tools rather than changing the work we do with the tools.
We spent some real time relaunching parts of the docs last summer. We added the Developers Guide which took a few weeks of Andy's time to write. We re-orged a bunch of pages. We threw a bunch of energy at it for a while, launched what we had, and left. Since then our efforts have been limited to approving other people's how-tos and thanking anyone who makes any edits during our monthly Town Hall. That's a very "hunting" type solution to the challenge.
There is no single big push of time that will result in perfect documentation we don't have to continually revise. Moving the nav from one side to the other, or even changing the tool we use to manage the content will not make the content more compelling. That's not to say the suggestions you make aren't valid, or that IA/navigations aren't important. I just really want everyone to understand we're trying to shift our energy here from the hunting engineer's perspective of "lets just make these changes so we can move on" into more of a product managers perspective of "what can I do today, and what can I do tomorrow to make what we have a bit better than what we had."
I'm following your thinking and your broader analogy, but this I think is the point where my broader suggestion may have got lost within all my description:
>> Moving the nav from one side to the other, or even changing the tool we use to manage the content will not make the content more compelling.
I'm saying that the actual doco content is there, but the overall and initial impression of the doco is missing the mark. The layout, the structure, the navigation, as well as the way it's managed all feels too complicated. I really struggle to find my way around it at times, and if someone like me, a concrete5 veteran encounters that, I worry about the impression it leaves on those checking it out for the first time.
Again that's not me saying the documentation platform isn't attractive, or well built, I'm just saying it's unconventional.
Presenting and managing the existing doco content how other successful frameworks are doing so is what I'm suggesting, something that new developers would immediately feel familiar with.
>> Moving the nav from one side to the other, or even changing the tool we use to manage the content will not make the content more compelling.
I'm saying that the actual doco content is there, but the overall and initial impression of the doco is missing the mark. The layout, the structure, the navigation, as well as the way it's managed all feels too complicated. I really struggle to find my way around it at times, and if someone like me, a concrete5 veteran encounters that, I worry about the impression it leaves on those checking it out for the first time.
Again that's not me saying the documentation platform isn't attractive, or well built, I'm just saying it's unconventional.
Presenting and managing the existing doco content how other successful frameworks are doing so is what I'm suggesting, something that new developers would immediately feel familiar with.
absolutely. Didn't mean for my reply to imply that your suggestions weren't valid. Just pointing out this needs to be an ongoing process, not just a one and done solution.
I didn't think you weren't dismissing my points at all, all good there!
I've had a bit of a think about the kind of layout and tree structure for the doco that I feel would work really well for a developer such as myself, and from that I've put together a couple of mockups. A lot of my thinking is really just looking at the Laravel docs and copying the kind of grouping of topics.
I honestly think the usage case is going to be quite similar to someone who developers with Laravel. With Laravel, I might as a developer go 'I want to cache this data, how do I do caching again?". A topic like that is then one level down in the 'Digging Deeper' section, and just one page. When you take a look at that section it's in, you'll see all the different facades and other common stuff like Mail, Events, Queues, etc.. Basically you end up mainly using that section once you understand the bigger picture of the framework.
(in my mockup I've just called that section 'Framework')
I think I really want to see that for concrete.. lots of doco about how to actually build the more complex things like themes and blocks (which I believe is already there and great), but then all the common developer task stuff in one easy to navigate list.
My ordering and absolutely selection of the documentation items isn't heavily thought through, I've gone for the general gist. I've not included third level pages, as where possible I'd be suggesting they be subheadings on pages. Maybe some sections couldn't avoid a third level, but those should be exception.
See the attached.
With what I've put together I'd be making a few further suggestions:
- Top level menu items either just open sub-nav or click to first sub-nav item.
- All development doco content to be presented in same format, no jumping to other page layouts (such as 'Framework' does in the current doco)
- Remove or place somewhere references to version 5.7 or 5.6
- Move out of doco version history
- No introductory pages that only have a few paragraphs, such as
https://documentation.concrete5.org/developers/security/overview.... That content is fine, but should then continue on with more content
- Remove or place elsewhere historical descriptions, for example the background and reasoning to the assets system -
https://documentation.concrete5.org/developers/assets/overview...
In no way I'm suggesting though a rework or rewrite of the content as such, more just a reorganisation into one, flatter tree, and perhaps the removal of content that doesn't add much to the understanding of how to do things now with v8. And obviously in the nice new look.
I still think having this content in markdown is the way to go, but to the end user it really doesn't matter.
Franz, I copied your new layout concept for the .org site, and could only get the general idea from the resolution of the video stream.. I apologise if I've butchered the finer details!
I honestly think the usage case is going to be quite similar to someone who developers with Laravel. With Laravel, I might as a developer go 'I want to cache this data, how do I do caching again?". A topic like that is then one level down in the 'Digging Deeper' section, and just one page. When you take a look at that section it's in, you'll see all the different facades and other common stuff like Mail, Events, Queues, etc.. Basically you end up mainly using that section once you understand the bigger picture of the framework.
(in my mockup I've just called that section 'Framework')
I think I really want to see that for concrete.. lots of doco about how to actually build the more complex things like themes and blocks (which I believe is already there and great), but then all the common developer task stuff in one easy to navigate list.
My ordering and absolutely selection of the documentation items isn't heavily thought through, I've gone for the general gist. I've not included third level pages, as where possible I'd be suggesting they be subheadings on pages. Maybe some sections couldn't avoid a third level, but those should be exception.
See the attached.
With what I've put together I'd be making a few further suggestions:
- Top level menu items either just open sub-nav or click to first sub-nav item.
- All development doco content to be presented in same format, no jumping to other page layouts (such as 'Framework' does in the current doco)
- Remove or place somewhere references to version 5.7 or 5.6
- Move out of doco version history
- No introductory pages that only have a few paragraphs, such as
https://documentation.concrete5.org/developers/security/overview.... That content is fine, but should then continue on with more content
- Remove or place elsewhere historical descriptions, for example the background and reasoning to the assets system -
https://documentation.concrete5.org/developers/assets/overview...
In no way I'm suggesting though a rework or rewrite of the content as such, more just a reorganisation into one, flatter tree, and perhaps the removal of content that doesn't add much to the understanding of how to do things now with v8. And obviously in the nice new look.
I still think having this content in markdown is the way to go, but to the end user it really doesn't matter.
Franz, I copied your new layout concept for the .org site, and could only get the general idea from the resolution of the video stream.. I apologise if I've butchered the finer details!
my 5 cents:
I've been with concrete5 for over 10 years. Some goods and bads exist in all packages. The worst drawback with such an exceptionally great CMS as concret5 has always been its documentation. I am sure I would have reached the level I am at right now 8 years ago if the documentation had also been exceptionally great too. But it's not. Its biggest problem is I've got no idea what's available in the core, what classes, properties, methods are available unless I spend hours, days, sometimes weeks digging into the core myself, searching forums, Slack, internet. And sometimes I don't find answers I'm looking for and I simply give up, a few times even giving up on this CMS altogether.
Some more experienced developers, PRB tell me I have to dive into the core and find all answers myself as a developer. Ok, somewhat a valid point. But, the difficulty finding what I need frustrates the hell out of me.
My personal favorite documentation is Qt:
http://doc.qt.io/qt.html
Symfony (which Concrete CMS is based on) too has got beautiful documentation:
https://symfony.com/doc/current/index.html...
The way it's organized, structured, showing examples, links, explanations, interlinks and all makes starting with it and growing much easier and faster. Especially so even to a complete noob. Ability to navigate AND find is what's outstanding in Qt documentation.
It's not concrete5 documentation completeness which IMO is the problem, but it's its presentation and ability to find what I need. I think this is what should be improved dramatically. Especially the search, descriptions, examples. And I don't mean search by class name which I should know in the first place. It's a navigation search through the docs.
A lot of properties and methods in the docs in concrete5 don't say anything what they are and what they do, Add to this your trying to find how to solve something - it's impossible as you don't know what to look for and even if you find something it doesn't tell you what it does.
The Developer documentation (https://documentation.concrete5.org/developers/toc) is horrible from the point of structure and navigation. And the worst thing about it is it's not complete from the point of the total cocnrete5 functionality. Continuing with the Developer pages dilutes the effort and doesn't make a complete documentation after all anyway.
So, it's documentation, documentation and again documentation. The API docs should be combined with the Developer pages examples and the Cheat Sheet (https://github.com/shahroq/whale_c5_cheat_sheet):
1. Either documentation API with all descriptions, examples and interlinks IN the API doc pages, NOT in separate non-related site pages
2. Or it's the complete Developer pages for each class, property and method complete with descriptions, examples and links to the API.
That's all about developer documentation, I don't really use user/designer documentation.
I've been with concrete5 for over 10 years. Some goods and bads exist in all packages. The worst drawback with such an exceptionally great CMS as concret5 has always been its documentation. I am sure I would have reached the level I am at right now 8 years ago if the documentation had also been exceptionally great too. But it's not. Its biggest problem is I've got no idea what's available in the core, what classes, properties, methods are available unless I spend hours, days, sometimes weeks digging into the core myself, searching forums, Slack, internet. And sometimes I don't find answers I'm looking for and I simply give up, a few times even giving up on this CMS altogether.
Some more experienced developers, PRB tell me I have to dive into the core and find all answers myself as a developer. Ok, somewhat a valid point. But, the difficulty finding what I need frustrates the hell out of me.
My personal favorite documentation is Qt:
http://doc.qt.io/qt.html
Symfony (which Concrete CMS is based on) too has got beautiful documentation:
https://symfony.com/doc/current/index.html...
The way it's organized, structured, showing examples, links, explanations, interlinks and all makes starting with it and growing much easier and faster. Especially so even to a complete noob. Ability to navigate AND find is what's outstanding in Qt documentation.
It's not concrete5 documentation completeness which IMO is the problem, but it's its presentation and ability to find what I need. I think this is what should be improved dramatically. Especially the search, descriptions, examples. And I don't mean search by class name which I should know in the first place. It's a navigation search through the docs.
A lot of properties and methods in the docs in concrete5 don't say anything what they are and what they do, Add to this your trying to find how to solve something - it's impossible as you don't know what to look for and even if you find something it doesn't tell you what it does.
The Developer documentation (https://documentation.concrete5.org/developers/toc) is horrible from the point of structure and navigation. And the worst thing about it is it's not complete from the point of the total cocnrete5 functionality. Continuing with the Developer pages dilutes the effort and doesn't make a complete documentation after all anyway.
So, it's documentation, documentation and again documentation. The API docs should be combined with the Developer pages examples and the Cheat Sheet (https://github.com/shahroq/whale_c5_cheat_sheet):
1. Either documentation API with all descriptions, examples and interlinks IN the API doc pages, NOT in separate non-related site pages
2. Or it's the complete Developer pages for each class, property and method complete with descriptions, examples and links to the API.
That's all about developer documentation, I don't really use user/designer documentation.
The issue with our documentation is it tends to not cover everything from a no-experience go at it, and that then things get added that make parts of the documentation invalid.
When I first started to learn c5 it was a big learning curve for me, but I'm thankful and the community really made a difference. I eventually learned that the best documentation is the code itself. It would be nice not have to spend 3 hours trying to figure out a specific thing that could be documented by someone who knows it better. But if it had been I wouldn't have learned as much as I did.
I want to thank the team and the community members who have filled in the gaps for everyone for so many years via the forums and the prb.
When I first started to learn c5 it was a big learning curve for me, but I'm thankful and the community really made a difference. I eventually learned that the best documentation is the code itself. It would be nice not have to spend 3 hours trying to figure out a specific thing that could be documented by someone who knows it better. But if it had been I wouldn't have learned as much as I did.
I want to thank the team and the community members who have filled in the gaps for everyone for so many years via the forums and the prb.
Will you share new Concrete CMS graphics to use and promote the CMS?
We will.
My 2 cents. I always loved 5.6 docs and how easy I, personally, found them to use.
In comparison, the newer docs are hard to navigate as @mesuva said. It's also much more content. I still agree with @mesuva's other point that the docs are not as limited as what people say, there's a lot available.
So back to my 5.6 comparisons, there's probably lots to gain by infusing some simplicity and order in the docs as @mesuva said. Familiar patterns are important.
Laravel and WP have docs organized by function very often but also offer plenty of specific examples of achieving specific tasks.
Concrete is using a "trying to do this" approach as in "trying to create an attribute", "trying to update an Express entry"...
I think both approaches should coexist.
For example, when it comes to Express it's good to have specific examples on how to create and work with entities and entries.
But when it comes to text helpers for instance it would be good to be sent in the right direction from the doc. Each text helper already has helpful doc blocks in the code but if I don't know they even exist in the first place, that's not helpful.
In comparison, the newer docs are hard to navigate as @mesuva said. It's also much more content. I still agree with @mesuva's other point that the docs are not as limited as what people say, there's a lot available.
So back to my 5.6 comparisons, there's probably lots to gain by infusing some simplicity and order in the docs as @mesuva said. Familiar patterns are important.
Laravel and WP have docs organized by function very often but also offer plenty of specific examples of achieving specific tasks.
Concrete is using a "trying to do this" approach as in "trying to create an attribute", "trying to update an Express entry"...
I think both approaches should coexist.
For example, when it comes to Express it's good to have specific examples on how to create and work with entities and entries.
But when it comes to text helpers for instance it would be good to be sent in the right direction from the doc. Each text helper already has helpful doc blocks in the code but if I don't know they even exist in the first place, that's not helpful.
Forgot to mention these two more missing bits:
1. Although there are PHP API and PHP Developer pages, there's absolutely no information on Concrete CMS JS functionality - what's available, where (apparently not all assets work in user space), how to use it
2. There's no search functionality in Developer pages which makes it nearly impossible to find what you want unless you're already familiar with what's already there
1. Although there are PHP API and PHP Developer pages, there's absolutely no information on Concrete CMS JS functionality - what's available, where (apparently not all assets work in user space), how to use it
2. There's no search functionality in Developer pages which makes it nearly impossible to find what you want unless you're already familiar with what's already there
Great point about the JS functionality.
I wanted to follow up on the search functionality - I know that developer docs are indexed in documentation site search, but it sounds like that's not quite what you mean - can you elaborate a bit more on how you feel like search functionality for the Developer pages isn't meeting your needs there?
I wanted to follow up on the search functionality - I know that developer docs are indexed in documentation site search, but it sounds like that's not quite what you mean - can you elaborate a bit more on how you feel like search functionality for the Developer pages isn't meeting your needs there?
I should have been more specific. I didn't mean a keyword search, but search in general. Concrete CMS is based on Symfony which has got beautiful documentation (https://symfony.com/doc/current/index.html), why not follow the same approach? Symfony's documentation pages are delight to work with, you can easily find what you need most of the time because they're structured for humans.
As to the Developer pages:
1. Developers page looks terrible and ugly, like an incomplete dump of headings of examples without any order/sorting or sense
2. It's a list of examples, it's not documentation, the API is documentation, so calling the Developers pages documentation is misleading
3. There's no list of classes, there's no list of functionality, the cheat sheet (https://github.com/shahroq/whale_c5_cheat_sheet) is even better organized, much more meaningful and provides better search for what you need (visual, not keyword)
4. There's no information on how MVC is implemented (I mean you can't find it in one place unless you know exact page where to look), nothing on available entities, nothing on Doctrine (how to use it)
5. It's impossible to know which functionality is available in or from which version, the version number must be on each doc and example page
6. There's nothing on available 3rd party libraries
7. After a few attempts with attributes (following the Developers pages) in a package I just gave up and stay away from them, I couldn't get them to work - the info is either incomplete or incorrect
8. Majority of links to API are broken
9. Documentation should have a table of content, functionality, classes, descriptions and examples all interlinked with each other and API
10. My personal opinion is documentation for one thing should be on one page - it's easy to follow and to go back and forth, short usage examples (for methods) must be on the same page for the given method, some bigger complete functionality examples could be on other Examples pages and reference from the documentation page
11. There's very little on routing and there's nothing on limitation of Concrete MVC, e.g. how do I render a piece of php template code on a styled page? I also gave up on this because it's impossible by following the docs.
12. Permissions is another headache. Unless someone tells you on Forum how to solve your problem - you're out of luck, it's virtually impossible to figure it out on your own.
13. What are the assets limitations? Which assets can and cannot be used where?
As to the Developer pages:
1. Developers page looks terrible and ugly, like an incomplete dump of headings of examples without any order/sorting or sense
2. It's a list of examples, it's not documentation, the API is documentation, so calling the Developers pages documentation is misleading
3. There's no list of classes, there's no list of functionality, the cheat sheet (https://github.com/shahroq/whale_c5_cheat_sheet) is even better organized, much more meaningful and provides better search for what you need (visual, not keyword)
4. There's no information on how MVC is implemented (I mean you can't find it in one place unless you know exact page where to look), nothing on available entities, nothing on Doctrine (how to use it)
5. It's impossible to know which functionality is available in or from which version, the version number must be on each doc and example page
6. There's nothing on available 3rd party libraries
7. After a few attempts with attributes (following the Developers pages) in a package I just gave up and stay away from them, I couldn't get them to work - the info is either incomplete or incorrect
8. Majority of links to API are broken
9. Documentation should have a table of content, functionality, classes, descriptions and examples all interlinked with each other and API
10. My personal opinion is documentation for one thing should be on one page - it's easy to follow and to go back and forth, short usage examples (for methods) must be on the same page for the given method, some bigger complete functionality examples could be on other Examples pages and reference from the documentation page
11. There's very little on routing and there's nothing on limitation of Concrete MVC, e.g. how do I render a piece of php template code on a styled page? I also gave up on this because it's impossible by following the docs.
12. Permissions is another headache. Unless someone tells you on Forum how to solve your problem - you're out of luck, it's virtually impossible to figure it out on your own.
13. What are the assets limitations? Which assets can and cannot be used where?
I think the problem with the doc site is not the amount of information. There seems to be a decent amount of information. The issues in my opinion are how the information is organized and clearer coding examples. In the concrete5 slack group Mesuva has a concept mockup of the docs page. It looks very clean and easy to navigate. It reminds of Atlassian Confluence documents.
The real issue is the concrete5 (Concrete CMS) core team needs more help from the community as a whole. Portland Labs as we all know is a small team compared to the other open source projects on the market. So I think its up to us to step up and provide support. (Which I personally have been terrible at)
The real issue is the concrete5 (Concrete CMS) core team needs more help from the community as a whole. Portland Labs as we all know is a small team compared to the other open source projects on the market. So I think its up to us to step up and provide support. (Which I personally have been terrible at)
I have to agree with @mesuva and @linuxoid on documentation - new look is smarter but doesn’t help usability. +1 for @mesuva’s nice design approach example.
Positioning
Recent communication suggests concrete5 is to be positioned for medium to large organisations. This worries me.
As a small agency our bread and butter is what I would call smaller to medium sites - I think we’re fairly typical. I don’t want to be forced to use a separate tool to build the smaller sites, for me, Concrete CMS needs to work across a broad range of project sizes.
Ease of use (also positioning)
I love that I can build just about anything in concrete5 and easily add bespoke functionality.
That said, we are often competing against folks building on Webflow or Elementor/Divi etc. on Wordpress. Here a generic base template provides nicely designed wysiwyg customization options. A typically specified and well designed website can be delivered very quickly on these platforms by a designer with a relatively low level of web dev expertise.
concrete5 used to be ahead of the game here. Our Design and Layout tools have now fallen way behind the best available and the Style Customizer never really worked in the way it needed to.
It feels as if the core team’s thinking has moved away from the ‘customizable theme’. There is opportunity here - a modern open source CMS without the need for countless plugins and with a really good and thoroughly integrated layout and design system is a really compelling proposition.
Version 9 provides the opportunity to excel in our design and layout UX. The new ‘Containers’ are a good start but we need to go further…
Alignment with Bootstrap
The move to Bootstrap for Version 9 should allow us to integrate more tightly with the layout framework and appeal to the developers of the 20m+ Bootstrap sites out there.
To make the most of this opportunity we should expose more Bootstrap features - allow easy access to and control over styles defined in bootstrap classes, expose colors defined in BS themes, utilise the BS icon system etc.
I made some suggestions here:https://github.com/concrete5/concrete5/issues/9288...
A last thought, will we miss an opportunity launching Concrete CMS V9 on BS4 just as all the buzz will be around the launch of Bootstrap5?
Positioning
Recent communication suggests concrete5 is to be positioned for medium to large organisations. This worries me.
As a small agency our bread and butter is what I would call smaller to medium sites - I think we’re fairly typical. I don’t want to be forced to use a separate tool to build the smaller sites, for me, Concrete CMS needs to work across a broad range of project sizes.
Ease of use (also positioning)
I love that I can build just about anything in concrete5 and easily add bespoke functionality.
That said, we are often competing against folks building on Webflow or Elementor/Divi etc. on Wordpress. Here a generic base template provides nicely designed wysiwyg customization options. A typically specified and well designed website can be delivered very quickly on these platforms by a designer with a relatively low level of web dev expertise.
concrete5 used to be ahead of the game here. Our Design and Layout tools have now fallen way behind the best available and the Style Customizer never really worked in the way it needed to.
It feels as if the core team’s thinking has moved away from the ‘customizable theme’. There is opportunity here - a modern open source CMS without the need for countless plugins and with a really good and thoroughly integrated layout and design system is a really compelling proposition.
Version 9 provides the opportunity to excel in our design and layout UX. The new ‘Containers’ are a good start but we need to go further…
Alignment with Bootstrap
The move to Bootstrap for Version 9 should allow us to integrate more tightly with the layout framework and appeal to the developers of the 20m+ Bootstrap sites out there.
To make the most of this opportunity we should expose more Bootstrap features - allow easy access to and control over styles defined in bootstrap classes, expose colors defined in BS themes, utilise the BS icon system etc.
I made some suggestions here:https://github.com/concrete5/concrete5/issues/9288...
A last thought, will we miss an opportunity launching Concrete CMS V9 on BS4 just as all the buzz will be around the launch of Bootstrap5?
Absolutely don't want to take away from the broad appeal of Concrete just because we're trying to articulate a little better focus on who our ideal customer profile is here at PortlandLabs. There's something called "the halo effect" which explains that the harder you articulate who you are trying to serve, the more others find creative ways to use you for their problems too.
That said, the theme customization / containers / how do you make it easy to do CSS stuff without being a developer is a core challenge for lots of folks, including "the website manager with a team." I do think its important we get it right and welcome more collaboration on that github issue.
Regarding bootstrap versions, we're pretty comfortable being on latest stable even when there's a newer version out, and they do have a history of having pretty massive changes between versions. That said, it's probably worth considering the level of effort involved.
Thanks for the input!
That said, the theme customization / containers / how do you make it easy to do CSS stuff without being a developer is a core challenge for lots of folks, including "the website manager with a team." I do think its important we get it right and welcome more collaboration on that github issue.
Regarding bootstrap versions, we're pretty comfortable being on latest stable even when there's a newer version out, and they do have a history of having pretty massive changes between versions. That said, it's probably worth considering the level of effort involved.
Thanks for the input!
Sponsoring videos from up and coming YouTube dev channels:
We have all heard of people like the New Boston and Tuts+ but there are a lot of similar YouTubers out there with many thousands of subscribers, a video from some of these people would give a fair bit of reach for a reasonable cost, videos on how to build a basic add-on or theme, a video on just using ConcreteCMS and showing people there are alternatives to the big 3 would be beneficial, or even just a sponsored ad in the middle of one of their videos could reach a lot of devs who haven’t come across Concrete yet.
There are also quite a few channels on YouTube that just show how to use stuff in a basic way that receive a lot of views, if you search for anything to do with the WP theme “Divi” you will come across a lot of videos that are simple intros just for using the theme, if you could get some of these channels on board, this would cover some end user-focused marketing.
You could also do more video-based tuts and walk-arounds yourselves and expand your own YouTube channel, and even throw this out to the community you could get a lot of different content that way, but have it centralised on your channel.
Utilise blogging more:
Some more in-depth blog posts could work, you could mix up dev and user based articles, and throw in some human interest stuff too, the people behind ConcreteCMS, Andrew trying to retrieve his cat with the use of a dubious cat whisperer is a prime candidate. Again this could also be thrown out to the community for a wider chunk of content, and it wouldn’t be totally on PL.
Advertising on dev blogs:
This may be a bit hit or miss, but an eye-catching ad, maybe calling out WP with their “Gutenberg” editor which is a really poorly executed Concrete clone, may garner some attention.
Affiliate scheme:
Introduce an affiliate scheme for the marketplace incentivise members of the community to push clients/friends/relatives towards Concrete and its ad-on/themes for a small cut of the sale.
I am really excited for these changes in strategy and focus, the future of ConcreteCMS appears bright, which is totally deserved.