• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Paul Clapham
  • Tim Cooke
  • Jeanne Boyarsky
  • Liutauras Vilda
Sheriffs:
  • Frank Carver
  • Henry Wong
  • Ron McLeod
Saloon Keepers:
  • Tim Moores
  • Frits Walraven
  • Tim Holloway
  • Stephan van Hulst
  • Carey Brown
Bartenders:
  • Al Hobbs
  • Piet Souris
  • Himai Minh

Are there any good tools to make project documentation ?

 
Ranch Hand
Posts: 529
19
Eclipse IDE MySQL Database Tomcat Server Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I want to make professional documentation of my project. There are plenty of functions I used in my project to insert, update and fetch etc. records in database. I just want to make documentation so I could know which functionality of project( like Employee Registartion, Customer Sales from one date to another etc.) uses which method and which method returns what and fetches or does what and all, so I can avoid redundant methods which returns and does same job. Also will ease my workload If client request any changes or enhancements further. For this I need to have a list of methods with their features. Now I'm just writing method name, its usages, what it returns and where it is used in, all these information I'm writing in word file which is little uncomfortable. so any suggestion how to make documentation and if there is any good to suits my requirements or should I just continue with word file ?
 
Bartender
Posts: 689
17
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Ganish Patil wrote:I want to make professional documentation of my project. There are plenty of functions I used in my project to insert, update and fetch etc. records in database. I just want to make documentation so I could know which functionality of project( like Employee Registartion, Customer Sales from one date to another etc.) uses which method and which method returns what and fetches or does what and all, so I can avoid redundant methods which returns and does same job. Also will ease my workload If client request any changes or enhancements further. For this I need to have a list of methods with their features. Now I'm just writing method name, its usages, what it returns and where it is used in, all these information I'm writing in word file which is little uncomfortable. so any suggestion how to make documentation and if there is any good to suits my requirements or should I just continue with word file ?



Well for a start I would say use Javadoc. That is the standard tool to produce documentation of Java code. But it sounds to me like you want more than documentation, you also want some kind of visualisation of which methods call which other methods in the code?
 
Ganish Patil
Ranch Hand
Posts: 529
19
Eclipse IDE MySQL Database Tomcat Server Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Well for a start I would say use Javadoc.

Yes that I can generate from NetBeans IDE 8.0.2. which I'm using for my project.

you also want some kind of visualisation of which methods call which other methods in the code?

yes so I can know that ex. employee registration form which calls getNewEmpId() to generate new empId and insertNewEmpInfo() to insert new employee information in database.
 
Bartender
Posts: 10780
71
Hibernate Eclipse IDE Ubuntu
  • Likes 4
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Ganish Patil wrote:all these information I'm writing in word file which is little uncomfortable.


Because it's in the wrong place. Javadoc is the place you should put ALL your program documentation - including the more esoteric "how to use" stuff, which you can often put in package-based doc files.

Word®, oddly enough, is one of the worst mediums to document in. Powerpoint (IMO) is actually much better for the "narrative" stuff - especially if you might need to present it to someone - because it tends to keep the "woffle" to a minimum. And for diagrams or graphs, there is far better targeted software, like Visio (or whatever it's "morphed" into these days), which you can usually link into a PP slideshow (or indeed, your Javadocs).

The main thing to remember about documentation is:
  • Who is going to read it.
  • Why they're going to read it.

  • Almost everyone - myself included - write far too much documentation. And that's because it's not targeted. Unfortunately, most IT management still believes that "more is better", when in fact the opposite is almost always the case. Some of the best documentation I've read is very short; but it tells me stuff that wasn't available anywhere else, and I probably wouldn't have worked out for myself.

    My rules of thumb:
    1. With the exception of Javadoc, if ANYONE has to read more than 10 pages at once (diagrams included), they probably won't - so don't bother writing it.
    2. Trust your reader, and don't write stuff they already know.
    3. Document what IS; not what was, or what might be. The first is for revision systems, and the latter is for the intelligence (or imagination) of your reader.
    4. Smaller is better - documentation needs to be maintained; and the bigger and more complex it is, the less likely it'll be kept up-to-date.
    5. Link documents, don't import or embed them (see above).
    6. A clear, well-written program is the best documentation you can write.

    Hope it helps.

    Winston
     
    Ganish Patil
    Ranch Hand
    Posts: 529
    19
    Eclipse IDE MySQL Database Tomcat Server Java
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    Thank you so much Winston Gutkowski for such precious information. It helped me a lot
     
    Winston Gutkowski
    Bartender
    Posts: 10780
    71
    Hibernate Eclipse IDE Ubuntu
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    Ganish Patil wrote:Thank you so much Winston Gutkowski for such precious information. It helped me a lot


    You're most welcome.

    I should perhaps clarify one point: When I said "ten pages in one go", I didn't mean 10 pages total. A large system may need a hundred pages or more of documentation, but try to structure it so that nobody needs to read more than 10 "at once".

    In many companies, unfortunately, documentation is still regarded a "drudge work", and consequently is done by people who can't complain. In my last job, there was practically a competition among team leaders to see how much documentation (that THEY should have been writing) they could palm off to juniors who weren't competent to write it.

    Luckily, I had enough seniority (in years at least) to tell them where to shove it, but it's much more difficult for a newbie. I'd still definitely advise anyone who thinks they're being asked to document "above their pay grade" to query it as forcefully as they can.

    Winston
     
    Ganish Patil
    Ranch Hand
    Posts: 529
    19
    Eclipse IDE MySQL Database Tomcat Server Java
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    try to structure it so that nobody needs to read more than 10 "at once"

    yes I got this. Actually this is my first project and I have no experience what sort of situation I may face in future ( That could be database structure or any functionality etc. ) so just want to keep good documentation of my project ( Documentation just for my understanding ) so I'll be able to understand the functionality and its flow and all even after few years( Generally we forget which logic and function we used in the previous projects whose codes we haven't gone through since long time ).
     
    Winston Gutkowski
    Bartender
    Posts: 10780
    71
    Hibernate Eclipse IDE Ubuntu
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    Ganish Patil wrote:so just want to keep good documentation of my project ( Documentation just for my understanding ) so I'll be able to understand the functionality and its flow and all even after few years( Generally we forget which logic and function we used in the previous projects whose codes we haven't gone through since long time ).


    Actually, we rarely forget logic. Java is, after all, Java; and one presumes that you - or whoever reads your documentation - knows how it works. With very few exceptions, documentation is (or should be) about explaining what something does, not how it does it.

    What does sometimes happen though, is that we choose a particular way of doing something when there were several options available; and a well-placed note explaining why we chose that particular path can be invaluable. You shouldn't need to explain the logic to your reader though - and if you do, it probably means that you need to re-write your code.

    And on that subject, you might find this article worth reading.

    Good luck.

    Winston
     
    Ganish Patil
    Ranch Hand
    Posts: 529
    19
    Eclipse IDE MySQL Database Tomcat Server Java
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    Actually, we rarely forget logic

    yes, I think I'm little unreasonably worried about the uncertain future changes and implementation.

    documentation is (or should be) about explaining what something does, not how it does it

    Ohh Point jotted down.

    You shouldn't need to explain the logic to your reader though - and if you do, it probably means that you need to re-write your code.

    hahaha yes absolutely correct. I read the article It was really helpful. I never knew, We also have to think about reducing the memory usage as much as we can, which is consumed by objects(as Heinz Kabutz gave an example of String concatenation, I really adore and eager to learn how to write such clean code ). Also admire the point which Kirk Pepperdine made about DRY. Once again much obliged for your advice.
     
    Winston Gutkowski
    Bartender
    Posts: 10780
    71
    Hibernate Eclipse IDE Ubuntu
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    Ganish Patil wrote:Once again much obliged for your advice.


    You're most welcome, and I wish you luck (although I suspect you may not need it).

    Winston
     
    I've got no option but to sell you all for scientific experiments. Or a tiny ad:
    Garden Master Course kickstarter
    https://coderanch.com/t/754577/Garden-Master-kickstarter
    reply
      Bookmark Topic Watch Topic
    • New Topic