documentation could be better

fidesmo / gradle-fidesmo-example

3 stars 4 forks source link

documentation could be better #3

Closed krasch closed 9 years ago

krasch commented 9 years ago

I found this example project through developer.fidesmo.com. When trying it out myself I ran into some issues:

After reading the docs I had no idea what the resulting javacard app does. Could you please add a short summary?
It would be nice if you could add a download link to the Javacard Development Kit (there are so many versions!)
I also had some trouble figuring out what to do with the Ant Tasks. I since found out that I should just unzip those in the same directory as the development kit. Might be interesting also for others.
Setting up "fidesmoAppId" and "fidesmoAppKey" seems like it should be part of prerequisites or at least be described before listing the commands. When I first tried to run a command (without having set up that stuff) I directly got an error message

Thanks!

slomo commented 9 years ago

Thank your for your Feedback, I am working on it.

slomo commented 9 years ago

@krasch I had some issues reproducing the last issue you mention.

To clarify: The fidesmo appId is needed to list the available task via ./gradlew tasks. Therefore it is given in the build.gradle file, but even if you would remove / or uncomment it you would be prompted when it is required, the plugin shouldn't crash.

There are some gradle specific issues with this behavior, when running with the --daemon option, if you are using an up-to-date version and still experience error messages, it would be very helpful if you could provide a trace by running with -S --info appended.

krasch commented 9 years ago

@slomo Sorry, I was probably being misleading. When I ran any of the commands without having set up the appId, I was prompted for it, just as you say. Nothing crashed.

I just felt that from a documentation perspective, one might consider the appId/appKey configuration a part of the setup process and would want to describe it before listing the available commands. Otherwise users might not understand what the plugin is asking for. On the other hand this is described right afterwards, so my "complaint" is really not that important.