Documentation: A major hurdle to OpenKIM adoption.

OpenKIM
1

Dear all,

I am sorry for criticising your otherwise excellent project, but I think you need this feedback.

I was resuming working on some OpenKIM related stuff after a brief hiatus. In the mean time, version 1.9.2 has been released, and I noticed that installation is now a completely standard configure - make - make install procedure. Great work!

Still, if I had not known how to proceed, I would have given up. After installing OpenKIM, I wanted to install some models. I remember from earlier that there is now a script that can maintain a collection of models. Armed with that knowledge, I began looking on the web page for documentation reminding me how to use it. Soon, that turned into a search for any kind of information about how to install models. I found no mention of the script whatsoever. In the contrary, I found many places stating that you should install models from source, with links to the database of source code but no hint as to how to “install from source”. In the end, I looked for the script in the installation folder (I knew it had to be there) and fortunately it gives a decent help text when called without arguments.

I am afraid this is the greatest “threat” to the OpenKIM project. It will never take off if people cannot find out how to use it - either because that information is not on the web pages, or because new users cannot find (or understand) the information.

I suggest that you write a simple OpenKIM Getting Started guide - one that does not try to take all possibilities into account, but just handles the simplest cases. I will add such a guide myself to the Asap documentation (which certainly suffers from the same problems, by the way - this is difficult to do right!)

With my best regards

Jakob

2

Dear Jakob,

Thank you for your message. We couldn't agree with you more. In fact, we are in the process of improving our documentation. Your message prompted us to expedite the installation instructions for the KIM API and KIM Models.

Please take a look at the new documentation at the following link and let us know if you have any suggestions for improvements:

https://openkim.org/kim-api/

Best,

Ellad

3

Dear Ellad,

Excellent. This is exactly what is needed - short and to the point, referring corner cases to other documents.

Just make sure to make it really easy to find from the front page.

Best regards

Jakob

4

Hello,

Thank you very much for the great project! I cannot agree more with Jakob’s comment. You must have had more feedbacks from other users than me, but in my case as a new user, I have been reading different parts of the project two full days, and finally I haven’t even successfully installed open-kim. Now I am totally lost and don’t really know which and where instructions I should follow to accomplish installation.

For example, on this page https://openkim.org/kim-api/ under the “Using KIM Models” section, as a very new user, I don’t know how I should run that given piece of code? Is there any instruction somewhere I have missed? I feel the project would very much benefit from simple to-the-point example instructions and scripts (removing optional details) such that the user could exactly replicate. Otherwise every new user should ask for help during installation and usage.

Thanks again and best regards,
Alireza