Comment by rosalinekarr | Hacker News Reader

Comment by rosalinekarr | Hacker News Reader

I thought this project was really cool when I first came across it, but there was one thing that really offended me about it and made me refuse to ever use it:

> How to Use It

> =============

> Use the source, Luke ;)

> Please note that impress.js was created for developers. Some basic knowledge of html, css and javascript is a prerequisite to install and use its features.

So, in other words, "please, reverse engineer my work because I'm too lazy to document my code."

Sure, they've put in a lot of comments, but there's still no clearly defined interfaces or guides for use. It's all comments like 'delegated handler for clicking on step elements' and big ascii art of yoda.

Documentation is not just for _newbs_. It's an important part of making a third party library. If you want other developers to use your code, then make it easy to use. To not do so is incredibly user-hostile, and it's not going to get you anywhere.

Could you imagine if people had attitudes like this in other fields of engineering? "Here's your new car." "Thanks, how do I change a tire or put in gas? Does it have a manual?" "Manual? Just read the schematics. If you know anything about mechanical engineering or combustion, you should be able to figure it out!"

> Could you imagine if people had attitudes like this in other fields of engineering? "Here's your new car." "Thanks, how do I change a tire or put in gas? Does it have a manual?" "Manual? Just read the schematics. If you know anything about mechanical engineering or combustion, you should be able to figure it out!"

This is basically giving away the schematics to a car, not a car itself. If someone gives you the schematics for a car, you still need to know a fair bit about reading those schematics (and a fair bit about a lot of other stuff) to work out exactly how to build the car.

Impress.js isn't being delivered as a complete product, but it is a free project. I don't work with Impress.js except as a casual user, but as I understand it "Pull Requests Accepted", and if they aren't, fork Impress.js into Impress.js-with-docs and add them if you feel you must. The entitlement to someone else's time is tiring.

I understand the frustration but your analogy broke down for me when you added the "idiot." I interpreted this to mean that the developer chose not to put additional effort into documentation. While I understand this can be frustrating, Impress.js is still a pretty cool project and I'd rather it exist without documentation than not exist at all.

That was a reactionary. I've removed it.

I've checked the repository. It has DOCUMENTATION.md in there (I guess some contributors take the initiative). The sample source code it self (the link with "Use the source" text) also has comment that explain how to use certain feature.

I think the need to replace the content of "How to Use It" section since they do have real documentation.

You're right. I didn't notice they had added that file. It looks like pretty comprehensive documentation too. I retract all my previous statements. They just need to update their README.

rosalinekarr we are always keen to receive feedback and suggestions to improve the docs, if necessary you can create a Pull Request so that we can improve it and make it less offensive. We have taken some actions recently on this matter: https://github.com/impress/impress.js/issues/540 and https://github.com/impress/impress.js/commit/967017115bd659a...

Reply on news.ycombinator.com