Introducing concrete5 Community-Driven Documentation
concrete5 has a documentation problem. It's no secret that we'd rather develop new features than take the time to write about old ones. This is hardly unique to us in the field of software development. Developers like to develop – not necessarily document. (Note: this is why we're hiring!)
It's not that we can't write good documentation: the 5.7 theme and block developer documentation is fairly exhaustive, covering a large portion of what's possible in 5.7 with a mix of code, narrative and screencasts; also, I like to blog, and see people understand and get excited about the work that I do. But I'm busy! As are the other members of the core team. Even this blog's been pretty silent over the last few months, as I've worked mostly on launching this, and concrete5 migration tools. Doing this level of documentation takes work – and keeping it up to date even more so!
This would be understandable and excusable if we had tools in place to allow our ample community to fill in the holes we've missed. Unfortunately, we haven't had those tools. Yes, we've had how-tos – and they've been helpful and a well-used – but they've had their own problems, including searchability and bugginess. Our editor and developer documentation has been managed only by us, and added to by us when we can find a spare moment. You've asked us to create a concrete5 wiki for years, and we've resisted – since the idea of using someone else's tools for what is essentially a content management problem seemed crazy to us. But at the same time we weren't doing anything about it. Now we have.
Introducing documentation.concrete5.org: your one stop for concrete5 editor documentation, developer documentation, tutorials and API! This site is an improvement over our existing site in every way:
- Built on concrete5 5.7
- Community Powered – anyone can sign in using their concrete5.org username and password and edit editor documentation, developer documentation and tutorials
- Easily submit new editor and developer documentation, as well as tutorials
- Tutorials offer the ability to specify which questions a particular tutorial answers, and then search by those questions.
- All documentation pages feature conversation blocks added to them, with the ability to monitor conversations via email.
- New API doc appearance, and the ability to download the API as a ZIP file
- Code snippets are automatically syntax highlighted
- Editor documentation uses WYSIWYG editing; developer documentation uses a completely new markdown editor, with support for drag-and-drop image uploading.
- All submissions hook into concrete5 workflows, so we can quickly vet and approve documentation.
There will be kinks, but we're committed to ironing them out quickly. We're really excited to see our documentation continue to evolve, and we're glad we can get some help on it. Check out some screenshots below:
