Documentation usage

4 posts, 0 answers
  1. Goran
    Goran avatar
    77 posts
    Member since:
    Feb 2011

    Posted 16 Apr 2012 Link to this post

    Hi,

    after one month of working with Telerik controls, the documentation is the last place I would want to go. Lets take an example:

    I would like to know more about RadTreeListView SelectionChanged event (its simple, probably everybody uses it, and probably all know what it is, but we should never guess, but always make sure we get it right). So I open silverlight online help:

    1. type SelectionChanged, I will get 147 results, and if you look at the list itself, most of them are meaningless, - there is no extra info.
    2. Lets try typing RadTreeListView SelectionChanged. I get 104 results... again list displays meaningless info - look at the first 10 items to understand what I mean.
    3. Lets try to search RadTreeListView class. NEVER use Tree-content on the left side, it is a pain to use it. You need to click on API reference, then wait for page to load again (???), then scroll down to Controls namespace, then wait the page to load again, then scrool waaaaaaaaay down to RadTreeListVIew, then wait for page to load again, then scroll waaaaaaaaaaaaaaaaaaaaaaaay down to RadTreeListView... I could save myself with half of the scrollings if page was not loaded each time I select something... never use table of context... instead use search... typing RadTreeListView, and then clicking on the class info,
    4. click on members, and then I can see that there are no inherited members... so now, if I need to find an inherited member, I will need to know from what class was it inherited. But I don't know that...
    5. I go back to Class info, there I see it inherits from GridViewDataControl (has link), and implements IThemable (no link). I will not speak about interfaces anymore, it seems that they are not documented at all.
    6. Click on the GridViewDataControl, then members, then search in events - nope, its not there
    7. GOing back to GridViewDataControl class info, to see what does it inherit. It inherits from baseItemsControl (link)
    8. Click on BaseItemsControl, then members, then search events - nope, still not there....
    9. Going back to BaseItemsControl class info, then see what it inherits - DataControl
    10. Click on DataControl, then members, aaand voila - finally I found it.

    Now think if RadTreeListView would list all events, inherited and its own, so I just need to look into members of RadTreeListView. I dont want to take credits for inventing this, this is already used on many websites that show documentation for particular software.

    Now lets discuss about information in documentation. Lets go again to members of RadtreeListView. I know you are tempted to use table of context, but dont, use search instead. We will look at the properties that are listed. What you see written in the description, you will see the same if you click on the property link. MOstly the information contain the property name with spaces, and added Get / set in front of it. Take the AutoLoadHierarchy. We dont know what is the default value, we dont see any explanation, so it is expected that you understand what it is. Why would I come to read the link then at all, what is the purpose of its existence? And there are tons of info like this.

    I know, if you put a lot of information, you would need to keep it updated, more work, but then again, your support should have less job buy answering support tickets and forum threads.

    Regards,
    Goran
  2. Hristo
    Admin
    Hristo avatar
    408 posts

    Posted 17 Apr 2012 Link to this post

    Hello,

    I am really sorry to hear about your frustration while using our online documentation. We are doing our best to keep all of the documentation up to date and as useful as possible. Thank you for your feedback, we will take into account when discussing the future improvements of our resources.

    All the best,
    Hristo
    the Telerik team

    Explore the entire Telerik portfolio by downloading the Ultimate Collection trial package. Get it now >>

  3. Douglas
    Douglas avatar
    2 posts
    Member since:
    Jul 2012

    Posted 14 Sep 2012 Link to this post

    I so agree. I was looking to post this myself but now that I've found this thread I am going to add to it. It is now September 2012, 5 months after Goran's original post, and I'm sad to say I don't see a significant improvement on the KendoUI docs page. Is there a team that works on the docs, or is it just a spare time task for the dev team?

    Here was the question I was faced with yesterday: How do I format the numbers on the x Axis of my Dataviz Bubble chart?

    I end up on the API page for the chart at http://docs.kendoui.com/api/dataviz/chart, and I search the page for "format" - not using the search at the top of the page because that frequently locks up Chrome for me (just the KendoUI pages, other pages are responsive).

    The nearest I get to a helpful answer is in the section: categoryAxis.labels.format String. The whole description (I'm not kidding) is: "The format of the labels." There is one example - setting to a currency format. Great - my axis is not a currency value. How do I format it? Where are the links to a page that will describe the formatting options? Even using Google to search the Kendo UI docs site often comes up empty. Saddest of all, I will frequently find more detailed information in the old docs site than the new one - many of the useful information snippets on that site did not make it over to the new docs site. 

    I am being frustrated at every turn with DataViz. Compare to the documentation for HighCharts at http://api.highcharts.com/highcharts

    ALL the configuration options, and I mean ALL of them are given to you in an easy to navigate tree on the left. When you click an option, you don't get terse and useless info like "labels.format - sets the format of the labels" - "No, really?" You actually get a full description of the default value, all the possible values, recommended usage tips and a "Try it" link that opens up an example you can see and change in real time to test the values. That should be the gold standard KendoUI docs are held to.

    Sorry this was more of a rant than I intended but I spent a fruitless couple of hours yesterday trying to get a chart formatted nicely to meet a project deadline and was unable to do so. I gave up and moved on to tasks I had some hope of completing.
  4. Dempsey
    Dempsey avatar
    8 posts
    Member since:
    Jul 2012

    Posted 03 Nov 2012 Link to this post

    I couldn't agree more. The Telerik Controls documentation should be a corporate shame for Telerik, and I do mean "shame." I have been appalled at the poor quality, the lack of significant information, and the uselessness of so much of the online Telerik documentation -- including most of the company responses in the forums. Why is this? I always thought most companies understood what a huge marketing tool that proper, useful documentation of their products was. I myself have written quite a lot of technical documentation for products, and it is truly not *that* hard! What's worse, this isn't the only complaint I've seen in the Telerik forums, so this must really be a serious issue with your customers/users.

    Is it possible to have a complete, honest answer as to why Telerik pays so little attention to their documentation?? If there are valid reasons, perhaps it would make our experiences with this chaff a bit more tolerable. If not, can we have some insight into if and when this situation might be remedied?

    Please don't get me wrong! I am a huge fan, but I *so* need to be able to raise my productivity level with Telerik Controls. Thus my genuine, sincere desire for better and more documentation (including the web site design itself!)

    Thanks,
    Dempsey

Back to Top