Coffeehouse Thread

34 posts

Forum Read Only

This forum has been made read only by the site admins. No new threads or comments can be added.

Software Documentation

Back to Forum: Coffeehouse
  • User profile image
    zhuo

    Hi

    I was wondering how many of you guys actually work for a firm that cares about documentations. Of course documentation could be at many different levels from code to higher level design documentations. 

    As analyst developers, what do you usually document? Can people provide the type of document you write along with a structure that you usually use?

    Cheers
    James

  • User profile image
    Manip

    Software Documentation? ... Do you mean comments in the code? Tongue Out

  • User profile image
    Sampy

    Comments in code? You mean unit tests?

  • User profile image
    zhuo

    Sampy wrote:
    Comments in code? You mean unit tests?


    I think software documentation can be applied at many levels.

    Business analysts would document requirements.
    Architect would write architectural documents.
    Designers would write design documents and
    Programmers would document within code and sometimes producing API documentations.

    I guess my question is to what extent do you document? Do you write any of the documents mentioned above? What structure or guideline do you use?

    If anyone here works for microsoft, what sort of documentation do you produce when creating a product?


    Cheers
    James

  • User profile image
    Sven Groot

    Sampy wrote:
    Comments in code? You mean unit tests?

    Please don't tell me you believe unit tests are an adequate replacement for comments. I once inherited a project whose original developers believed that. It was an extremely well developed application that followed XP coding practices to the letter, but it was still hell to get a grip on it due to the lack of comments. I ended up spending an afternoon with one of the original developers to really understand the code.

    Even if your project is really well designed, uses clear, consistent and consise identifiers and easily readable formatting, and has unit tests for everything, you still need comments!

  • User profile image
    Ang3lFir3

    Usually all i am responsible for (and require of the other devs in my team) is comments in code lots of them... and pretty ones too lol...

    and XML comments for intellisense etc... I require full XML comments for all classes...even those not in libraries...

    unit tests are great ... but as sven said... not a replacement for real comments.... gotta know why you did what you did.....and what the heck you were thinking

  • User profile image
    JohnAskew

    zhuo wrote:
    Hi

    I was wondering how many of you guys actually work for a firm that cares about documentations. Of course documentation could be at many different levels from code to higher level design documentations. 

    As analyst developers, what do you usually document? Can people provide the type of document you write along with a structure that you usually use?

    Cheers
    James


    The only firms I see that care about documentation are those who have the best products.

    Successful retail software companies nearly all have real documentation that is accurate and comprehensive.

    Bad shops "don't have time", they also have no standards for coding and little communication, and they always fail.

    Internal IT shops are most often like a bad retail shop, they "don't have time/ manpower " for proper documentation. Another reason that documentation is overlooked is that there is no audit trail produced between the meetings and the code, and no one demands that meeting notes become specifications. Folks just don't realize that documentation is as important as the code itself in many respects.

    I don't see much success without very good documentation.

    The only times I see success without documentation is when there is ONE programmer working alone who is working for themself ! Even then, to sell his company (or source code), he would have to create the documentation for his software in order to approach a group of investors.

    It is shameful how many do not properly document their efforts.

  • User profile image
    cheong

    As an inhouse developer, since client requirements change too frequently, the only "documentation for users" we can keep up-to-date is the ever growing "what's new" list between versions.  :O

    Upon 3+ years of continual development, I can tell you this list is long indeed. (Takes a few minutes to scroll to the bottom)

    Recent Achievement unlocked: Code Avenger Tier 4/6: You see dead program. A lot!
    Last modified
  • User profile image
    Frank​Palinkas

    Hi Zhuo,

    As the Senior Technical Communicator for my present employer, I work directly with both the development and QA/Testing teams.

    I write documentation sourced from both of these groups using xml, xsd, xslt, xhtml, css and DOM/JavaScript. I build .chms and from them web-based help documentation. I also build Client-Side XML Web Transformations to enable various individuals to use the deliverables. All work is validated against the w3c's latest recommendations for the code languages used and Web Content Accessibility Guidelines are adhered to for physically challenged users.

    Also, I build MSHelp2 desktop apps for VS 2003 & 2005 Help Contents windows based on API's, Class & DLL Libraries and Programming Guides. This data usually comes to me  in NDoc .chms generated by the dev team in the VS 2003 or 2005 IDE. You can learn how to do this by going to my Fast Track: MSHelp2 Integration TestCase/Lab in the Playground > Sandbox.

    At the moment, I putting together a new Fast Track TestCase/Lab detailing how to build Client-Side XML Web Transformations. It's in the review stage at the moment, and I'll post it as soon as it's finalized. This will enable you to produce cross-browser enabled XML transforms, rendering in IE, Firefox, Netscape and Mozilla browsers. It can be used for just about any type of documentation you want.

    Personally, whatever company I'm working with, I have to answer to myself as to the quality and excellence of my deliverables. If I'm not satisfied, I don't expect anyone else to be either. I consider this the rule, rather than the exception.

    Hope this adds a bit more to the conversation,

    Kind regards,

    Frank M. Palinkas
    MCP, MCT, MCSE, MCDBA, A+
    Microsoft Registered Partner
    Senior Technical Communicator & Web Accessibility Designer

  • User profile image
    irascian

    I'm with John on this one.

    It's my biggest (possibly my only "real" problem with "Agile") - the whole "we don't need no stinking documentation because we're REAL developers" argument. I've got no time for such developer machismo that seems to be an increasing trend with younger, inexperienced developers (who then wonder why their developer machismo has turned into an expensive and failed project).
     
    OK, so it's not good use of time writing and rewriting documentation that gets out of step with the code and becomes useless over time. Nobody wants to become "Accenture" or one of those other big consultancy companies whose main role in life seems to be churning out long, tedious volumes of documentation rather than real working code where every badly designed object property is described in great detail. But it's a much worse waste of time to have no documentation at all and then expect newbies to the code to become productive with a large codebase that nobody understands. 

    More often than not a lack of the basic documentation in my experience has shown a lack of design and the usual hobbyist mentality of "Let's just start writing code" which is all developers ever want to do because, heck, designing something first and documenting the basic decisions means you have to "think" (and, as we all know, thinking is hard).  And whilst "white board" design is used in agile shops, if you weren't in on that "white board" discussion (but stuck with maintaining/updating the code implemented as a result) and the reasons behind decisions aren't documented in the code you're quickly going to have an application that's been hacked to hell and back and becomes impossible to maintain. I've seen way too many "lipstick on a pig" (or "varnish all over a turd") agile products to think anything different.

    The whole assumption around "Agile" is that team communications are good and that everyone is familiar with the bulk of the code, and yet on every "Agile" project I've worked on that's simply not been the case - either because pair programming, stand up meetings etc haven't taken place, or because people have quickly been moved around and are never available when needed to "pass on the communication".  You can argue that they're not doing "Agile" properly, but in my experience this is very much the norm for many so-called "Agile" projects.

    Deadlines of a few days (or even hours) for change requests or bug fixes when the key person who wrote the code (but didn't document it) is on holiday or "too busy on something else you can't talk to him for a week" or has just left the company become an absolute nightmare without basic documentation, and wastes a lot of time and costs companies a fortune. Picking up code with thousands of small objects in and no documentation is a nightmare.

    So what do we need in terms of software documentation? Class Diagrams in VS2005 help (a lot easier than having 100 different class windows open trying to work out what gets done where as you step through the code), but in my experience rarely get created. Basic flow Diagrams and UML Sequence Diagrams would be enough basic documentation to get people into the code quickly, but because "real" developers don't do documentation this never gets done.

    And then we wonder why so many software projects are such a disaster in terms of coming in on time and on budget and being easily maintainable.

  • User profile image
    littleguru

    I'm doing XP and I'm doing documentations. Unit tests can't replace any documentation. You need to do both to be great. Code should be the way that somebody (somebody who does not know much about it) should immediately understand it. Therefore you need inline documentation, method documentation, documentation papers on features, documentations on the whole thing etc.

    I wouldn't even have thought to use unit tests as a replace for documentation. What a silly idea...

  • User profile image
    leighsword

    cheong wrote:
    As an inhouse developer, since client requirements change too frequently, the only "documentation for users" we can keep up-to-date is the ever growing "what's new" list between versions. 

    Upon 3+ years of continual development, I can tell you this list is long indeed. (Takes a few minutes to scroll to the bottom)

    Haha, 'what's new' is good enough, a great software doesn't and never requires its document, see, do you check out the documentation of Media player when you are playing music?

  • User profile image
    littleguru

    OMG! You are so naive. Everything needs a documentation, I don't know why software should be different. Good software needs documentation, because there is people that need to do updates and change code.

    Even if architects build houses they document everything!

    Your post is so out dated. Only lazy people are commenting in that way.

  • User profile image
    Lee_Dale

    Anyone who thinks documentation is not needed has never picked up somebody elses project and had to modify it.  However good the software is, every programmer is different and there are problems in software design and construction that each programmer will tackle differently. If your expecting someone else to pick up your work in the future then you should always let them know why you solved a problem a particular way even if your not you should still document as I can't count the amount of times ive written something then come back 6 months later and had to work out what i did.

    As a contractor I always make sure I provide a high level document of what I have done to provide the MD's and project managers with an overview of the software thats been created. I also provide a low level technical document for any techies that need to pick up my work and run with it.  On top of that EVERY class, property, method and code block is commented, in most cases i comment the code block before I even write the code which helps me and anyone wanting to know what I have done.

  • User profile image
    erik_

    At college I learn to document a lot, creating uml, requirements, etc.

    But each time we do a project somewhere they mostly got nothing more then the user manual. Which is frustrating because you need to figure out a lot, since the people that created the part (that now needs a little extention for our project) have no time at all or are not availible anymore. And we most of the time don't got weeks to figure out how they created this black box.

    Btw. how do they do this with opensource software? Do they for instance also create a requirements specification and lot's of uml diagrams, but keep that to themselves?
    Because all the stuff I mostly find that I want to extends doesn't contain much specs or diagrams of what they build or are planning to build and how they build stuff.

  • User profile image
    Manip

    erik_ wrote:
    Btw. how do they do this with opensource software? Do they for instance also create a requirements specification and lot's of uml diagrams, but keep that to themselves?


    lol... Most OSS projects have NO documentation... The ones that do are the exception.

  • User profile image
    irascian

    Manip wrote:
    
    erik_ wrote: Btw. how do they do this with opensource software? Do they for instance also create a requirements specification and lot's of uml diagrams, but keep that to themselves?


    lol... Most OSS projects have NO documentation... The ones that do are the exception.


    Tell me about it. Even the "big hitters" typically point you at a crappy Wiki which has little useful info on it or (in the case of NDoc - shame on you!) is a link that gives an error.

    And if there is documentation the assumption is ALWAYS that you're from the MTV generation and suffer from Attention Deficit Disorder so that the only way to read documentation is on screen.

    Don't get me started on how hopeless the chm format is for printing stuff that can be read on a commute! 

  • User profile image
    Manip

    <Sniff> Your mean... Some of us just prefer reading stuff off the screen...

    [My left arm for Adobe Reader to support some form of bookmark]

Conversation locked

This conversation has been locked by the site admins. No new comments can be made.