New Marketing Strategy for Concrete CMS
Take your time to give me some good ones, and I'll make the time to answer them here.
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.
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.
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.
if you're looking for the beta signup for new community ^^^
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.
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:
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 -
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.
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.
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."
>> 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.
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 -
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'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:
Symfony (which Concrete CMS is based on) too has got beautiful documentation:
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.
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.
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
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?
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?