Chartist-js: worst API ever

[yairEO]

It doesn't explain anything. nor does it make sense. I've been programming in javascript for 10 years now so i'm no stranger to it and to APIs, but this one is a mystery.

First of all, nowhere is explained what are the parameters you might pass, for example, to a _line_ chart. I see you can pass data, but what else? where is the full list?

In the API page, the first thing you read is Module Chartist.AutoScaleAxis, but what does this name means?? how should even use object variable shown in the API? for example, I want to disable the vertical axis for a line chart. what is the parameter for that? searching the word vertical show no results.

There are all these functions and code..but how should one use them? use-case examples?

This whole API is one big WTF
I'm not trying to be annoying or anything, I myself have been open-sourcing a lot and if I think so, I guess countless other devs are also frustrated by the lack of proper documentation

[gionkunz]

If you're interested in the usage of line chart API you should look for http://gionkunz.github.io/chartist-js/api-documentation.html#chartistline-function-line in order to see the parameters for line charts. You can see the parameters for the Line constructor listed. In order to check the available options, just expand the default options. There are also simple usage examples directly there. This is an automatically generated documentation based on JSdoc. There are maybe a few drawbacks with automatically generated docs, but in therms or maintenance this is definitely the way to go.

If you have specific ideas please go a head and give constructive feedback.

[yairEO]

it most certainly does not say what are all the available options to pass to the line function. I quote:

The options object with options that override the default options. Check the examples for a detailed list.

There is nothing useful in the examples below. This API is really shit, you should re-write everything, so people could actually use this library instead of wasting countless hours understanding how to do a simple thing.

An API must state all the available parameters a function can take, and this API doesn't even to that.

I don't know what JSdoc is, but I guess it generates some low-quality API from real code. Since obviously a developer can't understand anything from the API, then what is the point? The library took you countless hours to create but you won't take the time to properly explain how to use it?

[andrewflon]

.. and yet many other developers have managed to use the API for this rather nifty royalty-free graphing library to get themselves set-up.

I'm quite a novice developer yet I managed to quickly follow the documentation and figure out how to setup everything to get some great-looking charts working with my application.

.. and the developer (Gion) is very active in answering questions and providing free, incisive support for his library - much more than most other libraries I've seen ..

If you're such an experienced developer yourself, I'm surprised you're having such trouble following the documentation - or knowing that you don't get much help online by acting like an asshole.

[bartveneman]

@yairEO I'm not sure if the tone you're using in your comments helps to have a healthy discussion. I suggest we keep discussions here to the point and refrain from using all kinds of wtf's.

In addition, I find the docs clear enough for most cases and if I really must dive in deep I have a look in the source code. Any experienced developer should be able to do that.

Also, I'd like to remind you that this library has not reached a stable version yet and therefore I understand completely that @gionkunz hasn't taken the effort to make the docs 100% bulletproof. And because this is an open source project, you can help to make the docs better! That's one of the good things any developer can do, experienced or not.

[yairEO]

Your comment doesn't address the fact that the job of an API is to explain what a function does and what can be passed to it, and yet, it does not say what are the things which can be passed.

Your specific needs might not be as the next person, and you cannot possibly know how many devs switched to another (one of the countless other free) library because they could not find what are the options to be passed, and how to fully customize a chart.

I am surprised you are surprised. I just said couple of times a full list of settings that can be passed is not in the API, so how would I know what are they? regardless of my experience as a developer, I cannot guess parameters names, it's like guessing lottery numbers.

[timwis]

@yairEO when you phrase feedback like that, it leads authors to believe the community is unappreciative of their work and demotivates them. I know because I've been there. It's an unfortunate reality that when you open up feedback to the whole internet, you get some knuckleheads once in a while.

Surely you understand that the author has absolutely no obligation to appease you - this is an _open source_ project. If it's not good enough for you, fix it! Submit a pull request. Alternatively, there are plenty of other charting libraries out there. But for the sake of all of us who benefit from the author's continued work on this project, leave out the negativity, the profanity, and the rudeness from your comments.

[yairEO]

@timwis

1. Not everyone are from united states and share the same culture of speech. you are a part of a global planter, and in my culture it is normal and encouraged to be as open as possible about your real views and feedback. Stop mixing feelings with computer programming, it will not help in anything. we are programmers and shouldn't feel "bad" because someone on the internet said API sucked. that's childish. instead it would be wiser to look inwards why would a person say such a thing. doesn't matter in what manner was it spoken, since you cannot imagine how my culture is, just accept the content of the feedback.
2. I cannot submit pull-request since I don't understand the API. It's absurd to tell me to write something which the whole point in this discussion is saying that I don't understand that very thing. The logic contradicts itself here.
3. I myself have been doing open-source for years and have many active projects. I'm not just a random douche from the internet who only takes and never contributes back. I am doing my part daily.
4. The whole point of having your code open-sourced is so others could use it. the creator probably spent months creating this. so saying he has no obligation to "appease" me is totally counter-productive to the essence of open-source, and soul of it, which is to make your project available to the public so as many people would be able to enjoy it as possible. why would you make a project and then make the community's life extremely difficult by not taking the take to write a proper API seems illogical, wouldn't you agree? unless the creator is under the illusion that his creation is as obvious to others as to him, which a creator should never assume. That would not make his open-source project truly "open".
5. I am deeply deeply sorry to have offended you guys, I love your project it is awesome and I have high respects for anyone taking the time writing open-source, regardless if I find it good or not. Helping the global community is the most important thing a programmer could do.
6. Sorry if my English isn't perfect.

[bartveneman]

Alright, since the back and forth compliments aren't leading this issue anywhere useful, let's try to pinpoint what we could do to contribute an actual improvement. So my question is: what would be a good first step to improve the documentation? What's the biggest thing missing?

[yairEO]

well, the "API documentation" page lack texts which clearly states what are all the available options you can pass when creating a Pie, Line, or Bar chart. it just says "Check the examples for a detailed list." but there is no such "detailed list" in the examples shown. just say right there what are the options, better than sending a poor person into a research across the page which will be futile.

another thing which seems odd is the clutter of internal methods and functions which seem irrelevant to the API, such as "extend" which for some reason appears twice and is obviously some internal method which merge objects. If a person wants to merge object, with today's libraries and way of coding, he should be doing this by himself, and it's irrelevant to the context of the code, which is graphs rendering.

The main question is why would a person go this the API page and what answers would he find there? common sense suggests a user would like to configure his graph to be just the way he needs it to be, therefor, if a user wants a line chart without the "Y" axis or whatever other settings, he will look for all the available options under the CHARTIST.LINE section. that is the most logical place to look for answers. All those tons of other irreverent functions and methods only cluttering the API. For example the section: SVG-PATH.JS says "Chartist SVG path module for SVG path description creation and modification." okkk what did I just read? there are no examples why would I ever need this method nor the countless which follows it.. would be of great value to understand the usecase and the thought which was put behind those functions and in what scenario would they be of help.

I could go on

[gionkunz]

@yairEO Are the default options with comments not enough to find all available options?

Actually I'd not like to remove the internal functions from the documentation but maybe we could flag them as internal or separate them into a different section?

Certainly some more inline jsdoc in the headers of the functions / modules would help too.

[yairEO]

@gionkunz - well, lets see. A regular dev comes to the API page, wanting to configure their line chart. he clicks the defaultOptions link under the CHARTIST.LINE title on the side menu. He sees no options, and the title of the section it leads isn't what he/she just clicked on. Where are all the option they wonder? maybe scroll down? scrolling shows this:

var options = {
  width: '300px',
  height: '200px'
};

obviously these aren't all the options. where are ALL the options? a dev needs a list and he needs it now, not by gathering bits of options from scrapes of examples scattered around. Even if they did scroll down, they won't ever see a coherent list of all the available options and what each does. For example, where does it say that there a fullWidth option? nowhere. I had to dig it up, charging my client time for this, which in result he was wondering why it takes me so long to create graphs the way he wanted. (in some specific way) well, if the API was good it wouldn't have taken me so long to find how to set things up, saving time and money for my client. now double that with couple hundred devs which are facing the same problem. thousands of human hours wasted world-wide...for what? so difficult to have one single list of all available options and what do they do? maybe even a section of commonly used setups which one could simply copy paste? Maybe open a thread in the issues where people can post their setups in JSBIN or whatever and you can use those links in your site for examples. just ideas from the top of my head.. thanks for reading!

[janpio]

@yairEO You have to click on "SHOW CODE" next to "declaration defaultOptions". This will open a list of all default options. This is probably what you want. Correct?

(Still, a simple "Where can I find all the options for line charts?" would have been the better ticket.)

[skibz]

that is the most logical place to look for answers.

actually, that would be the source code.
if you find the documentation to be lacking, perhaps write some yourself.

[Zache]

@yairEO

[yairEO]

Ha thanks, now I see. never thought that a list of settings will be refereed to as "code". Never in my life I would have thought clicking that button. Instead of getting angry maybe you should re-think the UX. sorry for not mind-reading how the API works. I get FAR dumber question on my projects from users and I answer them all and question my own README and tutorials so those questions won't be raised again by another.

[Swatto]

This is the most un-constructive issue that I've ever seen. For someone that present himself as a 10 years dev, never heard about JSdoc (the name is pretty closed to tons of other solutions to create documentation) and believe that it creates an "API" ...

[jbach]

@yairEO You do understand the sentence Expand the code view to see a detailed list of options with comments., though? No need for mind-reading.

[jpic]

@yairEO all the energy you've put in criticizing the docs would have been better spent improving them. Phrasing inspired from http://www.catb.org/esr/faqs/hacker-howto.html

[yairEO]

Nope, never heard about JSdoc, shoot me. I can give you examples of things I use which you also have never heard about.. that's not the point. Sorry, didn't see the "show code" button. I thought the test was referring to some other code later on and thought it was really weird.

guess i'm just used to APIs which looks like this - http://jqapi.com/

Sorry to have made ya'll so mad, just didn't see that button is all

[ajwhite]

I'm just going to leave this here..

I've been programming in javascript for 10 years now so i'm no stranger to it and to APIs

..

Nope, never heard about JSdoc

Sorry to have made ya'll so mad, just didn't see that button is all

Behave like a big boy next time

[JesseTG]

You're on Y Combinator!

[yairEO]

@JesseTG - where? I haven't been on that website for like 6 years maybe

[petereberlecom]

i just grabbed some popcorn and watched the whole discussion. But i think its time to end the bashing? I know @yairEO could have asked a little bit nicer. But were all here for the same reason. To code and support eachother...

[ajwhite]

:one: for locking & closing this thread

[yairEO]

yeah and I was like "wtf is this shit where is all the API?" never thought about clicking that yellow button lol. soooo much time wasted on hacking and digging pieces of info from stackoverflow...ho well.

[ajwhite]

It's still no excuse to address the maintainers with such a demeanor. Being an open source contributor yourself, you should understand by now that this community is based on sharing constructive ideas, contributions, and collaborations. Not shooting someone down for their implementation or your lack of understanding in how to use it. Let's maintain a positive and progressive attitude and try to suppress our emotions when filing issues like this. Just uncalled for, man.

You should just apologize for the attack and move on.

[yairEO]

I am deeply sorry for being a jerk..

[Wingie]

@yairEO made my day :) it's not often you see a troll apologising.
I think the maintainer should feel proud that he has built such an awesome library that people would rather rant about lack of documentation instead of silently moving on to another charting library.
+1 to @gionkunz

[markentingh]

This is a perfect example of UX failure. I am with @yairEO on this one. I feel his pain because I too have had this happen to me. Why would anyone hide the most important part of an API doc, and then force the user to click a button to display the answer they've been so desperate to find? Not even Ctrl+,f search on the web page will display what we're looking for, not until the button is pressed. Pure UX hell.

[yairEO]

:+1: Yeah this is why I was so frustrated, ctrl+F didn't find anything on the page :/

@Wingie - The only reason I use it is because it's not Canvas and it's responsive. But it is not awesome, I was hacking my way to create the graphs I needed and the client is up my ass with why things had taken so long, well, who knew the API was hiding under my nose... For example, client wanted a filled area graph which has lines or divided into segments, where the user can highlight with mouseover each one see a tooltip. Good luck doing that. Or having a chart fill 100% of the height without AXIS. good luck with that.

[gionkunz]

I completely agree with some of the ideas here but you always need to consider priorities of developers working on a library. I have tons of things I'd want to enhance on the documentation site as you can also see from the open issues. There are lot's of things that can be improved in usability of the documentation but I just didn't had the time to work on this given other priorities like fixing bugs and implementing most wanted features. This is an open source project and everyone who has spare time and the necessary motivation can help to increase the quality of Chartist. Also I'm selecting most of my priorities based on open github issues, and this issue is the first one which criticizes the usability of the documentation site (expect a few small enhancements). This does not mean that the UX on the docs is great or even sufficient, but that there are just other things that are more important at the given moment.

If you have spare time, you're more than welcome to work on the documentation system. I spent some time to automate it nicely and building more UX on the documentation site should be quite painless.

All, I appreciate your comments on this and there's clearly a clash of different opinions. Not about the user experience of the API and Documentation (which somehow got mixed up here), but more about how to communicate feedback which starts with observing why things are done like they are. In the end, everyone involved here has spend time and energy in reading and commenting that could have been put into a constrictive collaborative work to increase the documentation (or just enjoying yourself and watching a funny cat videos on youtube).

All that said I think it's really time to close this issue and thanks again to everyone for their participation!

Cheers
Gion

[jpic]

@thesnackalicious​ if you had read the thread you'd had seen that @yairEO
already apoligized ... :)

[markentingh]

@jpic & @thesnackalicious ...why is it so important for @yairEO to calm your egos by apologising for expressing his frustrations about a poorly implemented UX feature that completely hides the most critical part of the documentation from the user's eyes, AND the browsers find box? You should let go of your selfish, childish pride for one second to realize that you should be thanking @yairEO for lashing out with anger, because who knows how many countless people had the same issue, got frustrated just like @yairEO diid, but then finally decided to click the stupid button before lashing out via a bug report. It makes me upset seeing so many people get offended by a user who is frustrated, demanding an apology, and STILL doesn't try to find a solution afterwards.

[jpic]

Your bad manners are only exceeded by your bad manners.

Dictated but not read.

[jamesbrauman]

@markentingh @jpic Immature of me to comment like that. I apologies to @yairEO and everyone else for any offence.

[jpic]

None taken, don't worry about it bro B)

[daN4cat]

I know this is a long thread, but I must thank this issue to have explained me that in order to read the default options I need to click the yellow icon "Show Code".

[RSI-sanjayyadav]

test

[njtech]

It doesn't explain anything. nor does it make sense. I've been programming in javascript for 10 years now so i'm no stranger to it and to APIs, but this one is a mystery.

First of all, nowhere is explained what are the parameters you might pass, for example, to a _line_ chart. I see you can pass data, but what else? where is the full list?

In the API page, the first thing you read is Module Chartist.AutoScaleAxis, but what does this name means?? how should even use object variable shown in the API? for example, I want to disable the vertical axis for a line chart. what is the parameter for that? searching the word vertical show no results.

There are all these functions and code..but how should one use them? use-case examples?

This whole API is one big WTF
I'm not trying to be annoying or anything, I myself have been open-sourcing a lot and if I think so, I guess countless other devs are also frustrated by the lack of proper documentation

Yeah I feel too that the documentation is completely lacking. For example, for a Pie chart, I scroll down to their documentation http://gionkunz.github.io/chartist-js/api-documentation.html#chartistpie-declaration-defaultoptions and there is no definite, and explanatory list of what all options can be passed and what does each option do.

yairEO is right IMO people just couldn't stand the tone haha

[njtech]

And the "Show Code" button - the so called solution - is not the solution. Does not give what is required of an API documentation - it just shows a sample code - as a developer I want to know all possible options, and what each option means. That's not there in "Show Code".

[f1ames0ff]

Agreed, documentation is fucked up.
Developers need to work on the documentation. I prefer to develop, not constantly digging through the source code wasting my time.
I did what I wanted, but it's took way more time than it could take if there were a good documentation.
Currently it's look like the library developed to be used by small group of people who already know how to work with it, but not for public usage.
Thankfully there is typings for the lib which makes examining way more easier than on plain JS.

[Instrumedley]

the guy did act a bit arrogant, but honestly he was right...this api documentation is awful. Please improve it

[markentingh]

the guy did act a bit arrogant, but honestly he was right...this api documentation is awful. Please improve it

Arrogant: having or revealing an exaggerated sense of one's own importance or abilities.

I think you need to learn English, @Instrumedley. @yairEO was genuinely confused and frustrated.

[Instrumedley]

the guy did act a bit arrogant, but honestly he was right...this api documentation is awful. Please improve it

Arrogant: having or revealing an exaggerated sense of one's own importance or abilities.

I think you need to learn English, @Instrumedley. @yairEO was genuinely confused and frustrated.

Thanks for the definition. So basically...being you