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.
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.
+1 would love to have more frequent documentation updates.
+10 on this. 5.7 is working very nicely now and really showing its potential - the docs need some love too.
++1
Lack of 5.7 documentation for is hurting the future of concrete5.
Lack of 5.7 documentation for is hurting the future of concrete5.
+1 Absolutely... Lot of good document are outdated now.
+1 Absolutely... Lot of good document are outdated now.
++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.
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.
+1
+1 Document updates will be really useful.
++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
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
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?
+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.
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.
+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.
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.
+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.
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 ).
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 ).
+ 1, and a do/don'ts page would be nice too (i.e. things that will change from Loader::helper to Core::make('helper/')).
+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.
+1 Docs are the basis for new devs.
I'd love to see more documentation, but we can all write "how to's" as well.
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)
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)
+1. Also, good comparison to the Arch wiki.
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/...
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/...
"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?
So what does this mean for the current state of the certification program? Is it even operational right now?
