Software documentation is written text that accompanies computer software. It either explains how it operates or how to use it, and may mean different things to people in different roles.

learn more… | top users | synonyms

2
votes
5answers
164 views

What is a generic term for name/identifier? (as opposed to label)

I need to refer to a number of things that have both an identifier value (used in code and configuration), and a human-readable label. These things include: database columns dropdown items ...
55
votes
17answers
4k views

How to deal with tautology in comments?

Sometimes I find myself in situations when the part of code that I am writing is (or seems to be) so self-evident that its name would be basically repeated as a comment: class Example { /// ...
6
votes
2answers
206 views

How do you track existing requirements over time?

I'm a software engineer working on a complex, ongoing website. It has a lot of moving parts and a small team of UI designers and business folks adding new features and tweaking old ones. Over the last ...
0
votes
1answer
568 views

How to structure process description documentation?

I'm writing a document describing process improvement recommendations. I have some best practices I've learned so far. I use those practices most of the time. But I suppose there are other ways to ...
6
votes
2answers
143 views

How to keep user's guide in lockstep with branches for a non-developer?

Our current user's guide is built using asciidoc. The documentation is managed by a non-technical person, but we keep the source text files as well as generated HTML in source control. Issues arise ...
10
votes
5answers
2k views

Is it a good idea to write requirements specifications by stories?

We're using agile methods in my current project at the moment, and we have heaps of stories like these: As an assistant, I want to pay a customer a refund so that they can get some money when they ...
3
votes
3answers
882 views

Generating code documentation

I want to generate code documentation in a simple format. The key items are Method Signature, members, constructors, methods. I am taking various applications in .NET and creating documentation for ...
11
votes
7answers
750 views

How can I document someone else's past work?

We're in a bad situation of having very little documentation on customization our past workers made to a business critical system. Lots of changes were done to Crystal Reports, database entities, and ...
9
votes
4answers
1k views

Prepare source code handover plan

Our company is about to acquire a source code of a huge product. What are thing to take into consideration when the handover starts, to make sure we have everything and be capable to maintain that ...
8
votes
6answers
1k views

What is a good non-technical example of a cumulative error?

I'm working on a report which needs to explain in non-technical terms the effects of a cumulative error, and why it is of importance to use absolute calculations. Definition of 'cumulative error' ...
3
votes
3answers
6k views

Are High Level Design and Low Level Design documents needed to follow Agile development process?

Our team is developing a project using an Agile development process. All of our requirements are converted into product backlog items and task are broken down based on that. One of my team member ...
4
votes
3answers
476 views

Documenting and enforcing programming standards and guidelines for shared library

Myself and another developer with the go ahead from our IT director have started a general purpose library in .NET with the intention that it will provide many common purpose classes that we use in ...
5
votes
6answers
575 views

Should I add MSDN notes or Stack Overflow links to source code? [duplicate]

Possible Duplicate: Is it OK to put a link to Q&A sites in a program's comments? I'm creating a powershell / C# host and want to add the following comment // This method cannot be ...
2
votes
3answers
548 views

Ways to present testing results

I'm doing a school project which requires us to create a computer application and then write documentation; therefore I have to write testing documentation, I already have a of test plan (Validate all ...
6
votes
5answers
358 views

How should I choose the right documentation for my team?

I've asked this question a few days ago about how much documentation should be made and now I realize I may have been asking only half of the question. My goal is to promote some sort of ...
9
votes
5answers
342 views

Determining the right amount of documentation

Where I currently work the general approach is - avoid documentation as much as possible Only document if a different team will need it just for clarification, I don't mean code-documentation - ...
20
votes
5answers
829 views

How-to convince company to start documenting for legacy software [duplicate]

It has been less than a year since I joined my current company. Their majority of sales have come from a single product that has been alive since the last 10 years. However, there is minimal (if at ...
0
votes
3answers
715 views

How do I write a specification? [duplicate]

Possible Duplicate: how do I write a functional specification quickly and efficiently With so many projects changing halfway - and clients assuming much can be changed at no additional cost ...
11
votes
1answer
271 views

Is iterative documentation development possible, and does it deliver effective documentation?

I have a project for university which I won't be starting immediately, but have been thinking about for a reasonably long amoung of time. I understand that University project development isn't like ...
7
votes
2answers
471 views

DRY way to write Javadoc on overload methods

I want to write Javadoc in DRY way. But the oracle document about Javadoc says write same thing again in overload method comment. Can't I avoid repetition?
2
votes
4answers
225 views

Document overall business architecture [closed]

I’m looking to document my business’ overall system architecture. I want to capture what system/s everything starts in, what systems it flows into and why, and where everything ends up. As part of ...
9
votes
4answers
1k views

Better way to train new hires

The team I currently am part of experiences fairly high turnover, with members typically moving to different projects within the same company. Currently our "training" for new members is to pair them ...
3
votes
3answers
390 views

Is this a good code documentation practice?

I'm working on 2 projects projA and projB, and both projects are maintenance projects. For projA there are 3 programmers and for projB there are 2 programmers. In each case all are working on ...
2
votes
1answer
169 views

Publishing an internal web app on the internet to a much larger group of users than before

My company has developed a web application based on GWT (Google Web Toolkit) and Ext GWT in the browser, JBoss application server and Oracle in the backend. The app allows users of different ...
2
votes
1answer
198 views

Would you choose a database or a dvcs as storage for a documentation wiki?

I'm about to start coding a documentation oriented wiki, as a pet project. The core features are: Extremely easy grouping of documents per version Markdown syntax (subset of) Multiple authors ...
12
votes
6answers
5k views

Software to organize and maintain project documentation, specification? [closed]

I'm looking for software to organize and maintain projects internal documentation, specification, requirements, etc. Currently we store all documentation as lots of MS Word DOC files in a source ...
0
votes
1answer
216 views

What do I need to include in my OOP design document?

I am a graduate student in aerospace engineering. A lot of my Master's thesis has been on developing an OOP software architecture in MATLAB to facilitate control of Arduino-based vehicles (blimps, ...
1
vote
3answers
1k views

What visualization method would you recommend for event driven programs?

What visualization method would you recommend for event driven programs? Are there industry standard diagrams, such as flowcharts?
1
vote
4answers
385 views

Design Document From Code

I am not much familiar with documenting/System designing stuff. I have to maintain an application written in C# - working as windows service. However there is no documentation for this system which ...
0
votes
2answers
190 views

Planning Development Projects

We are currently re-evaluating the way we manage, plan and run our projects (an area that I think we can massively improve upon) so I just wanted to get some ideas as to how other development teams go ...
3
votes
2answers
383 views

How to fix very bad code? [duplicate]

Possible Duplicates: How do you dive into large code bases? How do I handle refactoring that takes longer than one sprint? I have 2 files that cover 5000 lines of code. I have been ask to ...
2
votes
1answer
712 views

What should we include in SSAS cube design documentation?

What should we include in a SSAS cube design documentation? This is the initial phase of the document. I have included: data models, facts, dimensions, surrogate keys, hierarchies and levels ...
6
votes
8answers
498 views

How to manage your functional documentation?

Our functional / business documentation is spread across Word files on our corporate Intranet. It's difficult to find and update information. There has to be a better way. Any ideas? We had ...
5
votes
3answers
3k views

What is “Problem Domain”

I have to document my program for a school project and we have section called "problem domain" but I have no idea what to discuss in this section. So the question is: What should be discussed in the ...
59
votes
16answers
5k views

Do TODO comments make sense?

I am working on a fairly big project and got the task to do some translations for it. There were tons of labels that haven't been translated and while I was digging through the code I found this ...
2
votes
1answer
189 views

How do you define, organize, and document your data?

Please feel free to suggest a better name or way of explaining this question - I wasn't quite sure what to call it. The situation is one that may just come under the heading of "be organized" but I ...
11
votes
6answers
2k views

Self-documenting code vs Javadocs?

Recently I've been working on refactoring parts of the code base I'm currently dealing with - not only to understand it better myself, but also to make it easier for others who are working on the ...
2
votes
5answers
842 views

Why should you document code? [duplicate]

Possible Duplicate: “Comments are a code smell” I am a graduate software developer for an insurance company that uses an old COBOL-like language/flat-file record storage system. ...
2
votes
2answers
192 views

Local versioning system especially designed for documents

I have to work on some docs, I need a software that can trace all the modifications that I will make to a specific file or project (group of files): is there something like that? The important thing ...
9
votes
4answers
504 views

How to document and teach others “optimized beyond recognition” computationally intensive code?

Occasionally there is the 1% of code that is computationally intensive enough that needs the heaviest kind of low-level optimization. Examples are video processing, image processing, and all kinds of ...
5
votes
5answers
201 views

The value of an updated specification

I'm at the tail end of a large project (around 5 months of my time, > 60,000 lines of code) on which I was the only developer. The specification documents for the project were designed well early on, ...
2
votes
1answer
388 views

How do you write straight to the point documentation without looking sloppy and informal?

I'm currently at a contract position and am looking to add to the documentation of the projects I worked on, to assist the next hiree taking over my projects. The documentation I received was overly ...
5
votes
2answers
110 views

How to document/verify consistent layering?

I have recently moved to the dark side: I am now a CUSTOMER of software development -- mainly websites. With this new role comes new concerns. As a programmer i know how solid an application ...
1
vote
3answers
443 views

how to layout good documentation [closed]

I need to write out a documentation for developers to be able to use some API web software how should i lay out a documentation? What should always be included? And does it need to be really long or ...
3
votes
3answers
480 views

How can I convince my managers to enforce documentation standards?

I'm trying to convince another group in my company— that's about to hand code off to my group—that they need to provide more documentation in their source code, but they're treating it as a "nice to ...
8
votes
5answers
292 views

Should a method comment include both a summary and return description when they're often so similar?

I'm a proponent of properly documented code, and I'm well aware of the possible downsides of it. That is outside of the scope of this question. I like to follow the rule of adding XML comments for ...
4
votes
3answers
175 views

What could be some pitfalls in introducing a style guide and documentation generating software in a development team?

I'm considering using appledoc, a flavor of Doxygen for use in generating Objective-C code documentation, in order to create documentation for my company's iOS apps. The idea is that a server will ...
2
votes
1answer
280 views

How often do you take notes, and how are you able to maintain a consistent amount?

I take notes about language features, project details, etc. I've noticed that I tend to take a lot of notes when I start learning a new aspect of a language or start working on a new project, but then ...
7
votes
6answers
373 views

Can code be the documentation in open source developer tools? How frequently is it?

It's understandable that after a big development effort, some OSS authors deem reasonable that the project users should make an effort too in order to get started. Can the source code effectively be ...
2
votes
4answers
175 views

XML or HTML for User Manual/Help and Why?

I want to make User Manual/Help to my program. I found two good ways - XML or HTML - which should I use and why? I know how to do it in html (I know how to use js, css and such) but in XML it's ...