Nothing but love - but yeah, I get it. We should have more documentation. The funny part, is this is a complaint I see about Drupal, Wordpress - pretty much everything.. So yes, I agree. But with a long list of things to do, spending weeks writing books about concrete5 is just not realistically going to happen. (..and my money says people would still want something more/different.)
So here's what's up:
Andy and I are going to try very hard to screencast more. I think the most valuable piece of knowledge we can provide is "how to approach a problem" stuff. We're going to try to do a weekly show/screencast where take some open ended, well informed questions from the audience and offer some real answers. This should help.
What would help tremendously is if folks in the community could start pitching in here. We've had a couple of people write up short articles on something they've learned, and we've always been very good about quickly posting them to the help section, and giving the author credit and editing rights to that page. We would love to be doing that every day.
If there's something wrong on a documentation page, make a guestbook comment there and we'll clean it up. If you've got something new to contribute, PLEASE post it here so people can make sure you wrote it up right and if it's commonly accepted as correct, I will make sure it's quickly added.
If you've got a /specific/ idea for some subject or format of documentation that would be helpful to you, post that here and see if others jump on board with creating it.
As I look at Drupal's home page and see they are still running "documentation sprints" workgroups at events - I can't help but to wonder if this isn't going to always be the way that truly helpful documentation gets made.
If Andy and I have to write everything, not only is nothing ever gonna get done, but it will all be from our perspective and in our tone - which surely isn't helpful for everyone..
As I posted in the other forum(s), I for one will keep this posted. I may not get everything right, but I am sure you and the kind folks of the community will HOLLA if its wrong or way out there.
Anyway, thanks for creating our very own DOC forum.
Hi Franz,
I suggest you to have a look at Code Igniter's documentation http://codeigniter.com/user_guide/...
as everybody praises their documentation which basically is just the api with a thorough explanation.It would be nice to have something like that but nothing beats a fresh homemade hi-rez Video tutorial:)
with a little more in depth information about the underlying MVC and customizations and so forth...
My 2 Japanese Yens..
I have to second to codeigniter example - the truly useful thing in those docs is the 1 - 10 lines of example code they show by each function. I found this helped me enormously.
I would KILL to have some documentation like that for c5. So how can we make it happen?
I just suggested in another post that a c5 documentation wiki would be great. I've found lots of answers digging through the forums, but forums are not best for documentation.
There's plenty of decent open-source Wiki software out there (MediaWiki is the one I've used), but I'm thinking it would be a pain if it wasn't tied in to the existing c5 forums. Is that remotely possible?
There's a German c5 wikibook (http://de.wikibooks.org/wiki/Concrete5 ), but it doesn't appear to be very deep yet. Too bad I don't speak German!
Anyway, it's just a thought. Wikis aren't the be-all end-all, but I think it would be better than what we have now. And I think the c5 community is big enough to self-moderate something like that.
The reality is every month or two people come along and throw a lot of energy around about what would make the docs better, usually all around more software to manage it, when from my view, all we need is 100 more how-to and a better API.
You all write the how-tos, I promise to rethink the help section to organize them well and we'll get the API happier too.
its not really featured in any navigation, but it shows up in search. I think with a lot of hands-on love, the content there could become very powerful.
My experience has always taught me that changing UI & technology is a lot easier than content creation. If you all can help us build that FAQ out to a few hundred or thousand meaningful items, I promise I'll find the time to make it more browseable/searchable.
It's just as you'd expect in there, we have a FAQ page type and are careful to give pages good names, descriptions and a content block & guestbook in the main area. I can't say i'ts the simplest of submission processes, but again - having to use the concrete5 UI helps you clean up as you go.
So if you feel you can give a positive contribution to the FAQ section and have some time on your hands, lemmie know. I'll put you in a group that can work in there and wait to be impressed.
I've told you that I'll work about 6months or more with C5 in a team of 5 developers for the university. I know that we'll use the api extensively. This meany we will probably come into situations where we trial and error and solve problems.
What I'm trying to tell is that, we would like to help to improve the api, during our work. How will we be able to extend the api? I mean you can write "technical information" for available functions, you can add examples, write howto tutorials, answer faq's etc. Unfortunately all of these things are currently spread around on concrete5.org or I'm just blind as ever :)
Darn good point. I've actually been thinking of doing some tutorials (most likely screencasts) on my new found favorite open source CMS. If and when I ever get them finished, they're all yours to do with as you will.
Ditch the bells, whistles and screencasts, and spend your valuable time on filling in the missing information in the API reference. Currently there are whole classes that have dozens of methods and NOT ONE of them documented beyond just being listed, which my IDE can do anyway using ctags, thank you.
I agree. I love concrete5 and started to integrated in my team at OLA! Agency and I have some very good developers and the first things that point out is: Where the hell is that documentation in the API ? As a marketing point of view, lack of documentation will be the biggest reason why so many developers turn around.
This is my professional opinion. I also agree for everyone to participate in adding new documentations but where is the wiki ? We should need at least a better tool to contribute examples and code.
The PHP Official Wiki website is a good example.
I'm a fan of concrete5, I just wish I could say that it was Perfect but all developers that I show them, always tell me the same things, they said, poor documentation is a turn off.
I find it much easier personally to go to c5 ask questions and search forums rather than logging on to some wiki with of so much documentation that you can never find your answers.
Sure it takes a bit of time learning the ropes but at the end of the day between going back and forth between wordpress and c5 (which believe me I switched in one day about 10 times) I settled with c5 because of its easy editing and sweet addons.
Plus I hate not knowing what I am typing in our doing.
I have created about 10 sites so far and c5 is the way to go.
Plus I learn much easier when I see it. The screen casts enable me to have a larger picture and see that a system can actually work unlike reading pages and pages and then deploying.
So Personally....
C5 continue what you do! I love it and I will continue to make c5 sites!
I agree. I am a potential developer with C5 but I can't figure out how to allocate specific file folders (or sets) to each user so they can only select images that they have uploaded. It's in the API but I have no idea how to use the api methods to achieve this.
The custom forms allow users to upload images - eg avatars, how about an example of how to allocate that user a folder, or file set, for their uploaded images? (I bet it is one line of code!)
I'd love to contribute examples to the docs, but like most people here, I can't figure out how to do things that I can then use for examples! <g>
The scrapbook helper could need some kind of improvement for sorting, filtering and adding a whole scrapbook to an area with one function. (It would be great if i could sort it like the attributes in the user info block and if i could add a whole scrapbook to an area at the frontend).
Thanks Mose, but I want to do it programatically from a block, so a registered user can upload an image to a folder, then later select only from images they have uploaded. (All from the frontend)
e.g Like the Avatar form for user profile, but allow users to select which image they use for an avatar from any files they have uploaded.
The new(?) docs explain it better, but it appears to be back-end orientated.
@PurpleEdge... not sure if you still need this but the snippet below should list all files belonging to the logged on user...?
Loader::model('file_set');
Loader::model('file_list');$fs= FileSet::getGlobal();// gets all files in global file set$fl=new FileList();// create file list$files=$fl->get(100,0);// get first 100 files$u=new User();// gets currently logged in userforeach($filesas$f){// iterates through file listif($f->getUserID()==$u->getUserID()){// user uploaded file ??$fv=$f->getApprovedVersion();// get approved versionecho$fv->getFileName().'<br/>';// ouptut the file name}}
I've gone back to Website Baker, the framework is not as sophisticated/powerful as Concrete 5 but I am more familiar with it and it was more productive for me at this stage.
You might be able to do this with Dashboard->File Manager->Access. Put the user in a group, add that group to file manager access and then set their permissions to "mine". They will only be able to access the files they upload.
I get it. I'm not really a website programmer but even I can find the logic of Concrete5 by just perusing the code (base/models/packages). It's difficult, yes. The code is complex, unique and powerful - so, yes, it's going to take an effort. Typically, when I get into web programming it's because I need to "do something" with the code that is not found in typical packages or through typical web programmers. I have been struggling (for about 3 days now) on C5 code packages' inability to share certain logic - which is the obvious condition stemming from the upside ability to dynamically build a dynamic website.
In essence, the lack of documentation has been akin to someone shoving my face into the website and yelling "read it!" - or "Enough!" (-: Now that I've read it I'm not so gun ho on doing a screencast to show others what I just learned through extensive bleeding. More importantly, it begs this question: "If I show you this, I'll have to show you that. At what point do you dig for it yourself?" That said, I've left a few posts and got no replies - or, I should say no "replies in writing." The silence was deafening. (I found the obvious answer.) I find the people in C5 development forums willing and capable to help when the question and desire is true and thoughtful.
The business side of me understands the concept of time and resources. I say, "do what you do best." The C5 code is unique, powerful, thoughtful and extensible. It would seem to me that any web programmer who wants to gain an incredible advantage against his peers would invest the time to "learn it." And you don't really learn it by reading a couple of API sentences. You learn it by digging into it. The code is logical and open. You either got the will to jump on the train or you do not.
Thank you. Prior to C5 I would not have thought your approach was feasible. I can see the effort in terms of years. I'd feel the same way: "I give you the f...ing keys to the fastest car on earth and now you want an Owner's Manual? GET OUT!"
The Help section seemed to be missing some pertinent information about creating custom templates. I'm sure this info is all over the forums, but I made a write up and posted it. The "Ask Question" button in the Help section sent me straight to the builder forums, so I'm not sure if it's possible to "add to the guestbook" like you mentioned.
I apologize if it isn't a little more concise. I ended up talking about global CSS and the Design dialog a bit as well, since I think it's important for people to understand that there are several tools available to make their blocks look the way they want, and they should use the right tool for each job. Custom Templates are easy to make and powerful to use, but I still think that global CSS is a better solution in most cases. It bugs me when I purchase an add-on that won't take basic style changes without a custom template :)
I find this approach a bit of a cop out, frankly. You have an API? Document it.
I know this isn't everyone's view, but I have had a pretty poor experience trying to get answers to my questions, either through the documentation that is offered, by asking questions on the forums, and also via Twitter. Sadly, I'm pretty turned off by concrete5 at this point and don't plan to use it for client sites in the future.
I think the team has done a great job improving the help section recently.
In general, I think that Concrete is pretty well documented, or well thought out. Going to concrete5.org/api helps me, or just modifying an existing example of what you need to do. Starting with a working theme (like Plain Yogurt) or modifying an existing block is a pretty good place to start in knowing how themes and blocks work.
That said, I feel like we're given an awful lot for the price of "free".
I think I had the same sitemap issue you mentioned a while ago with Concrete 5.4. This ended up being a server configuration issue, and wasn't strictly inherent to C5. Windows servers, especially, haven't been tested as thoroughly, as the team all use Mac machines and Linux servers. I can't blame them. I try and tell my clients that my $10 unlimited Linux server will probably work better for them than their own server anyway. I think C5 hosting is down to $7 or so per site.
However, it's up to 5.4.0.5 now, and I'm not experiencing sitemap problems in any of my sites or servers. Occasionally significant point releases can have problems like this on isolated servers, but it doesn't usually happen, and the team is always quick to release a new version. I believe the fixes for 5.4 were out in less than a week. Considering that 5.4 marked a major overhaul in the sitemap, caching and layouts, I'll give them a break. I love that basically every add-on runs just fine, rather than experiencing a "DLL hell" style of add-ons that other systems experience.
I also see that you posted some questions with the ecommerce add-on ... I'll admit that the ecommerce add-on isn't quite as accessible as the core, but I still say it's years ahead of the other shopping cart systems I had to deal with. Can I use custom templates with it as easily as I'd like to? No, I guess not, but for $100, I'm still saving a lot of time and money going that route than dealing with some of the other solutions I've had to put up with. Merging a CMS with a shopping cart system can sometimes be a nightmare.
Seeing as Concrete is free and doesn't cost me $50K per license, I'm totally happy, and I accept that stuff happens every now and then. Everyone on the forums is donating time for free, too. I'm sorry that your experience has been frustrating
Code
Post Reply
Delete Post
You are allowed to delete your post for 5 minutes after it's posted.
As I posted in the other forum(s), I for one will keep this posted. I may not get everything right, but I am sure you and the kind folks of the community will HOLLA if its wrong or way out there.
Anyway, thanks for creating our very own DOC forum.
-Bill