Jump to content

  • Log In with Google      Sign In   
  • Create Account

[java] Good documentation of a library?


Old topic!
Guest, the last post of this topic is over 60 days old and at this point you may not reply in this topic. If you wish to continue this conversation start a new topic.

  • You cannot reply to this topic
2 replies to this topic

#1 javanerd   Members   -  Reputation: 122

Like
Likes
Like

Posted 29 January 2000 - 11:32 PM

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...

Sponsor:

#2 Captain Goatse   Banned   -  Reputation: 100

Like
Likes
Like

Posted 30 January 2000 - 03:00 AM

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.

#3 Jim_Ross   Members   -  Reputation: 122

Like
Likes
Like

Posted 31 January 2000 - 07:24 AM

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.




Old topic!
Guest, the last post of this topic is over 60 days old and at this point you may not reply in this topic. If you wish to continue this conversation start a new topic.



PARTNERS