Please sir, I want some more (an appeal for more 5.7 documentation)

Permalink 5 users found helpful
Hi Andrew,

It has been over a month since the documentation has been updated. I know that myself and others are very eager for new installments.

Is it possible to release documentation on a more frequent basis, perhaps weekly? This would give current users something to look forward to and assist others in adopting concrete5.

Also, if a typo is found in the documentation, what is the recommended way of bringing it to your attention?


Thank you,
Karl

P.S. for anyone else reading this who feels strongly about documentation, please post a reply.

MrKDilkington
View Replies:
goodnightfirefly replied on at Permalink Reply
goodnightfirefly
+1 would love to have more frequent documentation updates.
WebcentricLtd replied on at Permalink Reply
+10 on this. 5.7 is working very nicely now and really showing its potential - the docs need some love too.
JohntheFish replied on at Permalink Reply
JohntheFish
++1
Lack of 5.7 documentation for is hurting the future of concrete5.
APrather replied on at Permalink Reply
+1 Absolutely... Lot of good document are outdated now.
APrather replied on at Permalink Reply
+1 Absolutely... Lot of good document are outdated now.
hutman replied on at Permalink Reply
hutman
++1
With the number of changes that happened between version 5.6 and 5.7, the lack of 5.7 documentation is hurting the growth and transition of 5.6 developers.
HardOne replied on at Permalink Reply
HardOne
+1
edbeeny replied on at Permalink Reply
edbeeny
+1 Document updates will be really useful.
mnakalay replied on at Permalink Reply
mnakalay
++1 For more documentation, faster. It's more than needed.

Having said so, it seems some things are still subject to modification so it probably makes documentation less easy to write. 2 examples come to mind:
1- If you look at the existing doc for integrating redactor in blocks you'll see a note saying only for C5 5.7.4.1 and above.
2- Apparently in 5.7.5 some things are going to change with layouts and we will be able to add classes and style directly to a layout container
mhawke replied on at Permalink Reply
mhawke
We would all love the core team to hire 2 people whose only job would be to update the documentation on the fly but that isn't going to happen. As I see it, the biggest problem is what mnakalay mentioned above. The basic architecture is changing so fast that documentation efforts are often obsolete a few weeks after they're published so is it better to have incorrect docs or no docs?
nebuleu replied on at Permalink Reply
nebuleu
+1

The lack of a complete documentation was frustrating when I made my first attemps with 5.7. Thankfully the source code is generally self explanatory.
WillemAnchor replied on at Permalink Reply
WillemAnchor
+1
I can see it is very time consuming to write good docs.
I can also see that a lot of documentation is spreading out over the forum and the how-to's. Not always that easy to find a good answer...

Can't we setup the docs like on php.net, with User Contributed Notes ?
You would get direct input for the official docs, right under the subject.
And we would have a more structured place to post our findings and tips. It should be for answers only.
wildapple replied on at Permalink Reply
wildapple
+1 to docs and echoing WillemAnchor here on that user contributions attached to directly to docs. It would need to be policed in some way or it will end up like the discussions on the 5.6 docs though, which were always hit or miss in terms of being helpful.
jakobfuchs replied on at Permalink Reply
jakobfuchs
I completely agree. More documentation would be very welcome.

The docs that exist (especially the videos) are of very good quality in my opinion and also try to teach some concepts and not only "how to get task X done". On the other hand this leaves some room for a more short/concise type of documentation (like descriptions of API Methods etc.)

Obviously creating this documentation would take time away from development and other tasks, so it's a question of priorities.

And why not enable some form of commenting system with upvote/downvote functionality for the docs pages ( like the php.net docs, or wowhead.com :D ).
ramonleenders replied on at Permalink Reply
ramonleenders
+ 1, and a do/don'ts page would be nice too (i.e. things that will change from Loader::helper to Core::make('helper/')).
0xymoron replied on at Permalink Reply
+1 Would very helpful indeed. I would rather be able to work quickly and efficiently with the current features than have new ones added which I don't know how to use.
companyou replied on at Permalink Reply
companyou
+1 Docs are the basis for new devs.
madesimplemedia replied on at Permalink Reply
madesimplemedia
I'd love to see more documentation, but we can all write "how to's" as well.
derykmarl replied on at Permalink Reply
Another +1 As a newbie myself I've found it can be helpful to look back at the 5.6 docs in some cases and learn how things have changed in 5.7, but it'd be better to be able to skip this step and dive in facing forwards.

Loving the docs and screencasts that have been done so far though, they are very easy to follow - I'd go so far as to say the quality of what *is* there for 5.7 is up there with the likes of Arch Linux in how easy it is to understand for the complexity of what it's explaining (a big compliment in my book), but more detail would be awesome as I did find it gets thinner once you start customising things underneath and making your own blocks which IMO seems inevitable if you want to deviate much from the example Elemental layout.

(opinions my own not necessarily those of my employer)
SnowyMountainWeb replied on at Permalink Reply
SnowyMountainWeb
+1. Also, good comparison to the Arch wiki.
MrKDilkington replied on at Permalink Reply
MrKDilkington
It has been over 3 months since new documentation has been added, but there is good and great news.

The good news is that there is a new documentation and tutorial (how-to) system in place. Tutorials are much easier to write now with the ability to preview the markdown, upload images, and include HTML tags in code. New documentation pages can now be added and existing documentation can be edited.

"INTRODUCING CONCRETE5 COMMUNITY-DRIVEN DOCUMENTATION"
http://andrewembler.com/2015/11/introducing-concrete5-community-dri...

Everything is ready for community members to start updating current documentation, extending documentation, fixing occasional typos, and adding new documentation pages. As an open source project, the community should take an active role in working on this. Whether you are a user, designer, or developer, everyone has some concrete5 related skill, insight, or knowledge they can share. Even small contributions can add up quickly.

The great news is that concrete5 is looking to hire someone to be a concrete5 technical writer and evangelist. This will not only free up the core team to just focus on writing code, but will make a huge impact on concrete5's ability to grow and attract new users, designers, and developers.

"We're Hiring - Technology Evangelist / Writer

PortlandLabs seeks an individual who wants to teach the world about the power of concrete5.

We need you to spread the word about the many things that can be done with concrete5 by creating ongoing documentation, how-tos, screencasts, example sites, press releases, bylined articles, white papers, and more. You will also train site owners and developers and manage a certification program."
https://www.concrete5.org/about/we-re-hiring/...
campbell replied on at Permalink Reply
campbell
"You will also train site owners and developers and manage a certification program."

So what does this mean for the current state of the certification program? Is it even operational right now?