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

8
votes
3answers
740 views

Are XML Comments Necessary Documentation?

I used to be a fan of requiring XML comments for documentation. I've since changed my mind for two main reasons: Like good code, methods should be self-explanatory. In practice, most XML ...
8
votes
6answers
2k 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' ...
8
votes
4answers
5k views

How to document a project which is already developed?

I would like to know what options are available for documenting a project which has already been developed, as the developers who worked on didn't write even a single page of documentation. The ...
8
votes
5answers
816 views

What is the standard for modeling modern applications prior to development?

I'm taking on my first enterprise-level application and I want my team to model the entire ASP.NET MVC C# application before we even tap out one line of code. UPDATE: This was not intended to be a ...
8
votes
6answers
600 views

How to use unit tests as a source of information?

A colleague of mine was once at a seminar about agile development, where he heard it is possible to use unit tests as technical documentation. Something like using unit tests as an example of how to ...
8
votes
4answers
23k views

What is an “implementation plan”?

I was recently given the task of creating an implementation plan document. When I asked for an example of one that I could look at, I was told to look at the Project Plan that had already been created ...
8
votes
2answers
1k views

Documenting a programming language: Reference Manual

We are looking at revamping documentation across our product line. Part of that includes reference manuals for a programming language used as part of the system. When writing a reference manual for a ...
8
votes
3answers
1k views

Is there a Django reference?

I am new to Django. I have found the official topic guides https://docs.djangoproject.com/en/1.3/ an excellent place to learn from. But now I am in a place where I need quick reference to see what ...
8
votes
5answers
990 views

I'm tasked with leading the documentation effort for an existing, entirely undocumented, software product - what resources are there to help me?

I'm a software developer at a technology company. I have been tasked with leading the documentation effort for the product I work on. The goal is to produce documentation internal to developer, and ...
8
votes
6answers
2k views

On-the-fly graphical representation of code [closed]

I know about Omondo's plugin for live code-UML synchronization in Eclipse, but I was wondering if there was any other tool/IDE/IDE-extension that has some form of live graphical code representaiton ...
8
votes
3answers
320 views

How do I document necessarily complex code structures?

If I have a piece of code that is mathematically or structurally quite complex and irreducibly so, how would I go about documenting this piece of code? In particular, how can I ensure that someone who ...
8
votes
5answers
976 views

How useful are function points?

How useful is it to measure function points? We use function points at my new job. I've heard of function points but haven't had any training or experience... but I don't have much confidence in ...
8
votes
1answer
365 views

Are there any empirical studies about the effects of commenting source code on software quality, maintainability and developer productivity? [closed]

I am an advocate of commenting on source code and documenting software products. It is my personal experience and observation that working on source code that is rigorously commented has helped me in ...
8
votes
1answer
1k views

Splitting documentation between docstrings and sphinx

I'm using a combination of docstrings and Sphinx to document my Python programs. With Sphinx's autodoc, I can write a lot of documentation into the source as docstrings. Is there any standard for ...
8
votes
7answers
5k views

What should you include in a development approach document?

I'm in the middle of co-producing a "development approach" document for off-shore resources as they ramp up onto our project. The most recent (similar) document our company has used is over 80 pages, ...
8
votes
3answers
1k views

How does one read RFCs and similar documents? [closed]

RFC: Request for Comments (RFC) is a memorandum published by the Internet Engineering Task Force (IETF) describing methods, behaviors, research, or innovations applicable to the working of the ...
8
votes
4answers
2k views

Is functional spec a “design document”?

So I have been a bit lost in the terms, so first of all I present you what I have learned so far: System requirements specification - what users want, what the system should do Functional requirement ...
8
votes
5answers
311 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 ...
8
votes
5answers
1k views

What's the best way to store documentation associated with a code project?

We have a lot of documents associated with our software development. These include things like requirements, design documents, external PDFs, customer files, testing instructions, etc. Currently, ...
8
votes
1answer
1k views

How to document an algorithm properly with sample data?

I am wondering what should an algorithm documentation contain? Can't locate a proper guideline to follow. I have in mind to include summary of the algorithm description of the algorithm flowcharts ...
8
votes
1answer
626 views

Creating an effective C++ library website and documentation

Creating a C++ library also means documenting it so that others can use it, and that documentation can vary dramatically in quality. How should a website for a C++ library be structured so that it ...
7
votes
3answers
5k 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 ...
7
votes
6answers
405 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 ...
7
votes
5answers
1k views

Is a functional spec a part of the System requirement spec?

I wonder, sources like wikipedia or templates I found shows that Functional spec is a part of System requirement documents. I always thought that SRD is just overall decsription of the system, with ...
7
votes
9answers
1k views

Setting Up a Development Environment

I am part of an organization that is formalizing their software development processes/capabilities/etc. While the organization is not traditionally a software organization, they want to do this right ...
7
votes
3answers
2k views

Documenting a REST interface with a flowchart

Does anybody have suggestions on creating a flowchart representation of a REST-style web interface? In the interest of supplying thorough documentation to co-developers, I've been toying around in dia ...
7
votes
4answers
353 views

Should all developers on a team have equal role/responsibility in writing and updating software design documents

I've asked a very similar question few days ago, but because I presented too much of my company's current situation, most answers focused completely on something that I wasn't looking to answer. So I ...
7
votes
5answers
3k views

How do you balance documentation requirements with Agile developments [duplicate]

In our development group there is currently discussions around agile and waterfal methodology. No-one has any practical experience with agile, but we are doing some reading. The agile manifesto ...
7
votes
1answer
5k views

Template for Knowledge Transfer

I have been working for more than a year for this company. Now they want me to create a KT Document for reference. Is there any template available for me to document the coding done by me..
7
votes
2answers
211 views

Ubiquitous Language - conflict between correctness and usability

A core part of Domain Driven Design is the consistent use of a ubiquitous language across the system - in conversations, code, database schema, UI, tests, etc. I'm involved in a project in which ...
7
votes
5answers
171 views

Do you have any team guidelines regarding exceptions? [closed]

My team recently inherited a project from a team where the amount of developers dropped so low they had to offload some work. One of the projects we inherited was a project littered with nested code, ...
7
votes
2answers
5k views

Can you recommend a good test plan template?

Can you recommend a good test plan template for an agile testing team? I know there are templates for testing on the web and have already looked at some found by search engines, but I could really ...
7
votes
4answers
541 views

How to categorise information in end-user documentation?

One of the greatest piece of documentation I ever read is the TeXbook by Donald Knuth—the manual of the TeX typesetting system, and I used it in my first analysis. As far as I can tell, the type of ...
7
votes
1answer
2k views

Duplicating documentation on interface implementations/overrides good or bad?

So we have an interface like so /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos ...
7
votes
2answers
740 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?
6
votes
4answers
2k views

How can open source projects be successful without documentation about their design or architecture?

I want to improve my programming skills by studying famous open source projects, but I find it is easy to get lost by just jumping into their source code. So I decided to read their documentation ...
6
votes
10answers
419 views

What do I call people who extend my class in base class documentation?

Been calling them "implementers", but it seems weird to me. /// <summary> /// Implementers should implement this. Derp /// </summary> protected abstract void InternalExecute(); A point ...
6
votes
7answers
539 views

Commenting regular expressions

Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
6
votes
10answers
386 views

What's the best documentation you produce and why?

I think it's safe to assume that for most programmers, producing documentation is not as fun as actually coding. I think it's also safe to assume that most good programmers recognize the need for ...
6
votes
7answers
672 views

Does not documenting code result in job security? [duplicate]

Possible Duplicate: Should you write good documentation and clean code to increase the “Bus Factor”? I often ask young programmers why they are not documenting their code. Their ...
6
votes
5answers
635 views

Where should a programmer explain the extended logic behind the code?

I have developed a few quantitative libraries in C# where it is important to understand not only the classic information that goes with the XMLDoc comments (which contains basic information with the ...
6
votes
3answers
1k views

What are the best documentation patterns? [duplicate]

I've seen a lot of different ways to [or not to] comment out the code, specially patterns on desciptions of function details and file purposes. I'd like to know what is most used pattern to do that ...
6
votes
4answers
342 views

Are the technologies used in an application part of the architecture, or do they represent implementation/detailed design details?

When designing and writing documentation for a project an architecture needs to be clearly defined: what are the high-level modules of the system, what are their responsibilities, how do they ...
6
votes
4answers
952 views

Should user documentation include screenshots? [duplicate]

This question focuses on user documentation, not on code documentation. I just finished my software project, and the people I work for are expecting me to write user documentation, describing ...
6
votes
8answers
515 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 ...
6
votes
2answers
188 views

Is there something peculiar to Matlab or Mathworks that supports so much “undocumented” code?

I've been drilling into a lot of Matlab recently trying to interface with an in house algorithm engineer's work to modularize it for use in a test bench outside his suite of applications. I've come ...
6
votes
2answers
330 views

What's a good length for Javadoc for a class that is say 800 lines long?

I'm doing a code-review on someone's code for class. The class is about 800 lines long, contains a good dozen of functions but the description is like 1 line long. I'm wondering, generally ...
6
votes
5answers
378 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 ...
6
votes
5answers
282 views

Documenting higher-level concepts

I will be leaving my current project in a few days, and as part of securing my knowledge I have been asked to add comments to the code wherever I feel that can add value. The problem I am running ...
6
votes
2answers
233 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 ...