Software Documentation | The Coffeehouse

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

Manip

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

Sampy
This will be the sixth time we have destroyed it and we have become exceedingly efficient at it

Comments in code? You mean unit tests?

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

Sven Groot
My name has 9 letters. Coincidence? I think not...

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!

Ang3lFir3
Codito Ergo Sum

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

JohnAskew
9 girl in pink sweater

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.

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)

FrankPalinkas
Microsoft Help MVP

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

irascian
Irascible Ian

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.

littleguru
<3 Seattle

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

leighsword
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?

littleguru
<3 Seattle

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.

leeappdalecom
.nettter

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.

erik_
Tablet Power

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.

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.

irascian
Irascible Ian

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!

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]

leeappdalecom
.nettter

OOP is definately the majority used metholodgy, and id say get your head round that and you can turn your hand to pretty much any language. But bear in mind theres lots of other way of building software out there.

Kryptos
Backup People!

So any sugestions on books or links?

Kryptos
Backup People!

OK, I’m not a coder. I like playing around in VS2005 Express (used to use BASIC on Specturm, Comodore 64, VB3-6) and if I can think it most of the time I can code it, is it good code at least I think it isn't....

So here's my questions what is the best way to learn a method of coding, I see here that some people to UML, What is that? Is there a coding method or methods that should be followed?

I'm slowly getting my head around OOP....

I'm a hobbyist, but one who strives to things the correct way.....

EDIT: Cleared up smiley's, spelling

erik_
Tablet Power

Kryptos wrote:

So here's my questions what is the best way to learn a method of coding, I see here that some people to UML, What is that? Is there a coding method or methods that should be followed?

I am not sure if I have enough knowledge to explain this correctly, but here it goes:

UML stands for unified modelling language and is a standard language for modelling systems. You kind of create the blueprint of your software with it, before you start coding. So when you work with a team of people you are able to build on the same house and not build doors and windows that don't fit.

It also is handly to verify things with your customer, as some might understand the visual diagrams or are able to understand them with little explaining. If you try this with a bunch of code they will go wild!

Requirement are to get the 'what does the customer wants?' a process in which you will try to get all/most of the needs up front. So you are able to plan the whole project, instead of adding features on the fly.

Edit:

Google on uml tutorials and you probally get a lot of tutorials. There are also a lot of books on this subject, I got UML A beginners guide, but my gues is they all kinda explain the same. There is a MS press book about software requirements called software requirements second edition

zhuo

Kryptos wrote:
OK, I’m not a coder. I like playing around in VS2005 Express (used to use BASIC on Specturm, Comodore 64, VB3-6) and if I can think it most of the time I can code it, is it good code at least I think it isn't....

So here's my questions what is the best way to learn a method of coding, I see here that some people to UML, What is that? Is there a coding method or methods that should be followed?

I'm slowly getting my head around OOP....

I'm a hobbyist, but one who strives to things the correct way.....

EDIT: Cleared up smiley's, spelling

Can we stick to the topic please? Thanks

Kryptos
Backup People!

Sorry I didn't mean to get off topic, this just got me thinking in terms off what is the best practice for a single programmer?

Thus what documentation is required when there is a single programmer or maybe two? How much should be done or how little?

ScanIAm
On a scale of 1 to 10, people are stupid.

Sven Groot wrote:

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!

Sorry, Sampy, I gotta agree with Sven on this one. I'm sure I'm "Doing it wrong"* but even with the simplest tests, it may show you how to do something, but not why you would want to. I still think the /// comments at the top are cool and in some of the trickier areas, I'll comment each line.

Partially, because the wonders of "Refactor..." make it so that any joker with some free time can change the names that you've carefully chosen for clarity. Comments make it so you can at least figure out what you meant.

I love testing, though. It gives you that mid-project satisfaction that you didn't completely screw up. Sometimes you didn't know that for weeks Smiley

*I'm on a couple of these lists, and I cannot tell you how annoying it is to hear "Well, of course it failed, you did it wrong" as a response to any and all failed XP/Agile/TDD/scrum/whatever attempts. If the process is that difficult, natural laziness is going to keep it from ever reaching the mainstream. Or, maybe some of these practices need reexamination.