Archived

This topic is now archived and is closed to further replies.

[java] Good documentation of a library?

This topic is 6560 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

I thought I''d start a new thread as the "Fullscreen frames?" is not a logical heading for this discussion, but you can read from there the beginnings of this discussion. I''ve got to agree with both Arch@on and Jim_Ross. Documentation is the key to get people interested in any library. Unfortunately I thought the current documentation of GameFrame for Java was sufficient, but it seems I was wrong. The problem is that even the documentation I''ve written by now requires quite a lot of effort to keep it in synch with the changing library. As the library is still under version 1.0.0 it has changed quite a lot between releases, but I think the changes are becoming a bit more evolutionary than revolutionary in next few releases so it might be possible to write more comprehensive documentation. The remaining question is what kind of documentation is needed? Documentation is an interesting area as there is ongoing debate (even in the professional community) about what is good documentation of a program. I''ve allways thought that in order to get quickly up to speed you need: 1) A quick overview of the library that conceives the general idea behind the library. 2) Examples, examples and couple of more examples (with documentation of course) 3) The API reference propably in JavaDoc format. What is your opinion? If you have comments on what is wrong with the current GameFrame documentation I''d really appreciate pointing it out to me. As next release is upcoming in next few weeks I could fix a thing or two...

Share this post


Link to post
Share on other sites
Ok I give you one bad example: Java 1.2.2 documentation, It doesn''t tell how to use it. It just shows all basic and advanched commands but no how to use it. Like how to define int cursors in older versions, not now anymore because they are replace with cursor.defaultsomethingwhatever.

Share this post


Link to post
Share on other sites
Good docs of any library, I must say, should include code snippets of how to work with each key part of the library. For example, say you wrote a networking API, a bad example, in my view, would be giving some documented code on how to write a web browser. No one wants to look through a complete program to find out how to open a socket, write to it, and get the response back.

We all know how to get programs up and running. The libraries add functionality, so I feel that only small pieces of, "here''s how to do this, this and this and put them all together like this..." are best suited for the docs.

Share this post


Link to post
Share on other sites