I am no CKEditor guru at all. Just wanted to share some impressions after having read some documentation.
I like the introduction starting on http://docs.cksource.com/CKEditor_3.x/Developers_Guide. However, I have some difficulties diving into the API documentation. It is hard to read, and I can't find a good search function. An example...
On http://docs.cksource.com/CKEditor_3.x/D ... ide/Styles I read that I can use CKEDITOR.addStylesSet for registering a style definition. Now I want to read something more about the addStylesSet method.
Opening http://docs.cksource.com/ckeditor_api/s ... DITOR.html does not help. The method is not explained there.
There is a website search on the top of each page. Searching for addStylesSet only gives one hit. It is the mentioned page "Styles".
Searching for other method names almost always gives no hit. Isn't the API documentation included in the search? I do know about the "all:" prefix, and I did try this.
Or am I doing something wrong? Is there a better way for searching through the API documentation?
Michael
Thu, 08/12/2010 - 13:24
#1
Re: Feedback about the documentation
I am experiencing the same. There is a lack of examples. I am trying ckeditor 3, and I could not do anything.
There is also no tutorial about 3.x versions. And i could not find a community to answer my questions.
I thought that ckeditor, ex-fckeditor, was great as lots of people were talking about it, but i am very desapointed !
jujubre
Re: Feedback about the documentation
mgs, the API documentation is included inline in the source. If you want to read it as HTML, you'll have to do it online or process it yourself.
addStylesSet is just a synonym for stylesSet.add. stylesSet is a resource.
http://docs.cksource.com/ckeditor_api/s ... .stylesSet
The resource manager documentation hasn't been written yet because it's pretty low level. You should be able to figure it out from the examples though, it's pretty straightforward.
Jujubre, there are lots of examples in the _samples directory. There are tutorials on how to integrate ck into wordpress and drupal. And, gosh, you're right about no community to answer questions. *snort* If nobody's giving you answers, maybe you're asking poor questions?
Re: Feedback about the documentation
jujubre, my opinion is a little bit different...
- Starting with CKEditor is an easy task. Installation,and executing the samples, and following the "Developers Guide" is simple and straightforward. There are lots of samples distributed with the installation file.
- However, going one step beyond the basic setup is hard. After some hours, I have several problems that I a not able to solve from reading the documentation (all questions posted here in the forum). The only way to answering the questions myself would be to read the code and dive deeply into the subject.
sabr...
- "addStylesSet" being just a synonym for "stylesSet.add" is an interesting information. Where would I find such a piece of information? Or is it basic Javascript know how that I am missing?
- Why isn't the documentation for the API indexed? It is rather difficult to use CKEditor, if for example "addStylesSet" is mentioned exactly once in the Developers Guide and then no other place can be found where it is mentioned again.
Michael
Re: Feedback about the documentation
I grepped the source of course. In plugin.js:
// Backward compatibility (#5025).
CKEDITOR.addStylesSet = CKEDITOR.tools.bind( CKEDITOR.stylesSet.add, CKEDITOR.stylesSet );
In my experience that, while the Dev Guide gives a good high level overview, yery few answers are in the API docs. It's easier just to read the code directly.
Re: Feedback about the documentation
Maybe the Developers' Guide should be changed. It might be better to describe CKEDITOR.stylesSet.add there.
At least for me, having a more detailed documentation would be better. I do not intend to read and understand the sources. I am not going to change the source, I just want to use what is offered.
Michael
Re: Feedback about the documentation
For me, no answer means nobody knows.
php.net documentation, there are examples. jquery documentation, there are examples. mysql documentation, there are examples. I thought ckeditor would be the same, as it is widely used... but even in the documentation page, half of the index items are still not working.
So where is the "Detailed documentation", the "Full documentation, from the basics to advanced features".
Ckeditor is great fast and all that. That is why i am ising it. I am pretty confident that a solution exists. Now, I am going to find it on ckeditor's source code.
Thx for you poor answer.
Jujubre
Re: Feedback about the documentation
My main frustration though is not in ckeditors capabilities but in the countless hours one spends in searching for answers here. Simple things are often hidden deep within postings or documents.
What is lacking I think on the part of the developers in terms of the documentation is an understanding of its user base itself in a real world environment. The developers are obviously extremely good at coding, but lack the ability to translate things in terms or ways that the general average user can understand, what it is they are trying to explain. Bits of code do no good if you don't know what file to put them in or how they need to be properly placed within the file.
The other part of the issue here is the user of these support forums themselves. They ask questions in a posting and once they find the answers or solutions they rarely if ever return to post that solution so people see and other users become frustrated. Please users if you find an answer to your question return and reply back to your original posting with the solution and modify the subject with [Solved] at the beginning.
Most users here - myself included know just enough to get going and maybe do some slight modifications. All we really needed is good examples of how something is done to solve the issue.
Re: Feedback about the documentation
I've avoided weighing on on this till now, but I worked quite a bit with CKEditor this summer, namely converting our old FCKEditor installation to CKEditor. Coming into this with no knowledge of CKEditor, I found the documentation more or less useless. I referenced the API docs frequently, but usually resorted to searching the source code to learn and find examples.
I tried for the past month or two to answer every single question on the forums which I felt deserved an answer. Some answers got snarky, because I shouldn't have to answer the same question more than once. I answered one last week by simply linking to another post I had made, where I googled the answer for someone. Situations like this should not happen. I have lost all sympathy over the past month for people who cannot take 15 minutes and google.
A lot of my time was spent figuring things out on myy own, as this is the best way to understand a program. But posts like these: viewtopic.php?f=11&t=19843 I will probably not answer. I know I have answered this at least twice over the course of the summer. In addition, the post provides no context for the question. Furthermore, it's something that I feel could be easily solved by getting a clue and looking through the samples folder. Again, best way to learn.
I do, however, regognize that the search function on this forum is the most useless I have ever encountered. I told someone once that I had posted an example a little while ago which he might find useful. He was unable to find it, and when I tried it took me 5 minutes to find a post of which I knew its exact contents.
Too many questions on here are asked too many times, and I think it's due to peoples terrible laziness (Shame on all you) or ineptitude with programming. Do not come here expecting people answering questions to code out a new plugin for you. Often times, I feel like the language barrier can make asking and understanding questions difficult.
My advice is to simple use google to search the site. "My question site:cksource.com", it works pretty well. Next look in the _samples folder. Next read the API. Next, get firebug and debug it.
For more intermediate tasks, I think there is a basic lack of documentation. I wasted hours working on code in the _source/plugins/ folder instead of plugins/ folder. These common "gotchas" should be added to the FAQ or documentation. They are valid questions which everyone should know.
I guess in conclusion, I'd strongly urge for a fundamental change to the documentation. I don't know if wikis would help or not, but by making the documentation more accessible, more users will be able to jump in and contribute. In addition, everyone else will be more productive because they can spend less time answering and asking questions on these forums. It's no secret that documentation is the major shortcoming of this project, and the search function only compunds the issue. But I'm optimistic that with a few backend changes to the website and some more curiosity on the part of people asking the questions the support system as a whole can be improved.
Re: Feedback about the documentation
I think that it isn't so hard to understand that when there are four forums, one for FCKeditor 2.x and other for support in CKFinder, questions related to those products should be placed on those forums, and also, those forums should be used only for those products, but nevertheless, people keeps asking FCKEditor or CKFinder questions in the CKEditor forums, and they also post CKEditor questions in the CKFinder forums.
This is the first symptom that people doesn't care to read anything at all, they just want someone that answers their questions without taking care to read even the location of where they are placing their questions.
Something similar happens with questions related to Drupal, or any other specific CMS. Why are they posted here instead of searching the support site for whatever integration they are using?
The funniest ones are those that say that they have tried to add the zip as an extension to their CMS and it fails because it isn't recognized as a valid extension.
Then we have those that needs an answer right now!, they feel that they must bump again their topic over and over again, they won't care to try to help anyone else, they just want someone to answer their questions. Reading other topics might help them to understand their problem, but they are here just to get the answers.
The fact is that many of the questions can be answered by following the links in the FAQ: check the samples, it's really incredible the number of people that ask questions that are just as easy as loading the samples and looking at how they work.
If they can't be bothered to look at the files that they have in their own computer, why should they expect anyone else to answer their questions?
And all of them sum up to make the task of writing documentation a boring task, Should I really waste even a single minute to improve a doc, write a tutorial, create a sample if people is gonna ignore it?
What's the sense about trying to improve the docs?
Previously the docs in FCKeditor was a wiki open for anyone to improve it, but the reality is that only spammers bothered to write anything there, so it was just a waste of time cleaning up all that crap.
If you want to add some doc, write it in your blog and I'll link it in the FAQ. If you have some info that should be added to the FAQ just tell me and I'll add it.
If you think that you can edit the wiki docs, then you can ask Wiktor to give you write priviledges, but I think that it would be better if you can write that content first in your own blog and that will make it easier for him to check that you really know what you are doing and he won't have to waste his time cleaning up whatever mistakes that you have added. Managing your own blog is easy, and can be an easy way to write things that can be helpful for other people.
I've said this many times, but everyone has a different base knowledge so something that it's easy for some people it's hard for people with a different skill. For example I've skipped the questions related to PHP in the FAQ because I don't know what are the best practices there and how they should be handled (questions to magic quotes mainly) and so you can see every now and then people that say that their images look like src="\"path or something like that.
And that's not a question about CKEditor, it's a question about how they should code their CMS, but they lack that knowledge and think that these forums must give them the answers.
Re: Feedback about the documentation
I agree with many of the things you said and the problems users invoke with asking questions in the wrong sections and or repeatedly asking the same question.
I think there are 2 things that would go a long way in helping to reduce the amount of time users spend looking for answers before becoming frustrated and doing those 2 things mentioned
1. Improve the search function on these forms
2. Provide more full answers or replies - for example
with the Editor Toolbar I find the following link when search using toolbar:
http://docs.cksource.com/CKEditor_3.x/D ... de/Toolbar
Within it I find:
CKEDITOR.replace( 'editor1',
{
toolbar : 'MyToolbar'
});
CKEDITOR.replace( 'editor2',
{
toolbar : 'Basic'
});
What this neglects to tell some one is where to put that code - an example like this would be more helpful:
Place this after the Textarea field some place
</script><script type="text/javascript">
CKEDITOR.replace( 'editor2',
{
toolbar : 'Basic'
});
</script>
I think if this was done in this manner then that would greatly reduce the support time you needed to spend and users could answer a lot of their own question - faster and easier.
Just a thought
Re: Feedback about the documentation
So you say that every function, property, whatever must be provided with a full example because you don't understand how to use that example code with the provided full samples?
And then the next request I guess that it will be how to combine two of those samples, right?
Re: Feedback about the documentation