GeeCON Prague 2014*
The moose likes Servlets and the fly likes How to write documentation Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


JavaRanch » Java Forums » Java » Servlets
Bookmark "How to write documentation" Watch "How to write documentation" New topic
Author

How to write documentation

Eric Howell
Ranch Hand

Joined: Nov 26, 2000
Posts: 63
I wonder If someone could give me some pointers.
I am developing a demonstration portal application and this time want to fully document my app. Apart from documenting the source code I want to produce some application documentation.
Has anyone some advice about what I should include,what is expected order, layout, or even some links some documentation for other java apps.
I have looked on webappcabaret.com and most apps are not documented.
Thanks
Eric
Kareem Gad
Ranch Hand

Joined: Aug 06, 2001
Posts: 89
You need a full development cycle tool something like together control center www.togethersoft.com
and rational rose www.rational.com
You mainly need to model your business logic for the application in UML diagrams, and these beautiful tools do the rest for you.

tell me what you think.
------------------
KaReEm


<b><i>KaReEm</i><br /><ul type="square"><li>SCJP-Free Range Web Developer <br /></ul></b>
Mike Curwen
Ranch Hand

Joined: Feb 20, 2001
Posts: 3695

I don't know that everyone is able to buy a license for either Together or Rose. And plus, these are not going to produce documentation for you.

Really, it's a matter of process.

Make it part of your programming activities to continuously document your source code. The opposing view of course, is that 'comments lie'... but this is mostly because programmers do not keep comments synced with the code they are next to.

As for *user documentation*, my own opinion is that a programmer is the LAST person to produce this document. Someone that is a business analyst would be more appropriate.

Again though, if you are a one-man crew, or your company doesn't have a BA, you need to really step back and think like a user.

While not being patronizing, realize that the user has NEVER before seen the screens or webpages that you are intimately familiar with. Err on the side of patronizing though.. if a user is 'smart' then they can skim... if your user needs a lot of help, you will be a hero for spoon feeding them.

I cannot overemphasize the importance of good grammar and spelling when writing docs. I apologize if I offend anyone, but if your audience is English-speaking, then please have someone who has a STRONG grasp of that language write the docs. It looks pretty un-professional to have spelling mistakes in a document, and it's down right embarrasing(sp?)

As a tip, I know I certainly appreciate screenshots and a two column design in my documents, especially for a series of steps... so a screenshot in the left hand column, and the step in text form on the right.

Definately include a table of contents, and if you can handle it, an index. If you use Word, it can autogenerate (sort of) these things for you, which is cool.

And lastly, toot your own horn. Put your name down on that doc! You make yourself a target, but perhaps a target for praise.

As a last point, if you want, email me and I'll send you a draft version of a user documentation I made for a servlet-based editor toolset. It's pretty small, but you might get some ideas.
[This message has been edited by Mike Curwen (edited September 17, 2001).]
[This message has been edited by Mike Curwen (edited September 17, 2001).]
Dave Soto
Ranch Hand

Joined: Sep 15, 2001
Posts: 55
What Mike said about Rational and Together is absolutely true. And certainly documentation has to be a big part of your software development process, not an afterthought. And User Documentation really is just a matter of being, like Mike said, very aware of your audience.
That being said, UML is a powerful tool for documenting your software DURING the process, and even more powerful when development is occurring in teams. If you want to use UML for your development, but don't want to spend $5-$7K, try ArgoUML. It's free, it's easy, and you can create all the diagrams you need to with it. If you're interested, here it is: http://argouml.tigris.org/
P.S. Don't forget to JavaDoc!
Kareem Gad
Ranch Hand

Joined: Aug 06, 2001
Posts: 89
Dave, Mike and Eric for that matter,
When i recommended Together or Rose i frankly meant, but ofcourse was wrong to assume that the message got thru, that with CASE tools like these and others you cover the whole development cycle. So your business analysts would do the thinking and realise it in a standard UML form, doing all the note they want there in UML. This can then be passed to ppl who will do the implementation already now with some abstract documentation about the requirements in each part of the diagram.
So now the programmer or developer would have to only be cursed with the task of javadoc'ing his code; as he writes each module not after he finishes the whole block say. This assures that he describes it best while it is still fresh in his mind.
Dave you're totally right about UML, it is the best solution because it integrates documentation with implementation. Why i suggested to go for CASE tools right away is because they always give you the luxury of migrating from a UML diagram into code directly and you can link certain procedures on the diagrams with certain methods in your classes and thus providing an orderly flow in the module following the flow designated by the analyst.
I'll try ArgoUML, i hope it gives me the integration i get with Together.

------------------
KaReEm
Dave Soto
Ranch Hand

Joined: Sep 15, 2001
Posts: 55
ArgoUML isn't going to come close to Together in terms of functionality, and is by no means a replacement for it. But what it will do is give you a free tool to author UML diagrams. Good luck!
Eric Howell
Ranch Hand

Joined: Nov 26, 2000
Posts: 63
Thanks for taking the time to reply guys, its been really helpful. I'em taking all the info on board.
Cheers
Eric
Eric Howell
Ranch Hand

Joined: Nov 26, 2000
Posts: 63
Thanks for taking the time to reply guys, its been really helpful. I'em taking all the info on board.
Cheers
Eric
 
GeeCON Prague 2014
 
subject: How to write documentation