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
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
951 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
314 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
967 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
358 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
5answers
2k views

Why bother differentiating between functional and nonfunctional requirements?

I understand the difference between the two, but I get questioned by my colleagues of the benefit of labeling requirements as functional or nonfunctional (or transitional). Why bother to do so? He ...
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
601 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 ...
8
votes
5answers
3k views

Good references for End User documentation examples and advise [closed]

Our in house software has been used for many users and the training department asked us for any tips of end user documentation format. Does any know where can I find good examples of software end ...
7
votes
3answers
4k 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
397 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
347 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
210 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
170 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
1answer
996 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 ...
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
533 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
724 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
1k 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
535 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
662 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
606 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
339 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
900 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
2answers
165 views

How to make a large codebase easier to understand for new programmers

Suppose that I am developing a relatively large project. I have already documented all my classes and functions with Doxygen, however, I had an idea to put a "programmer's notes" on each source code ...
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
173 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
327 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
375 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
281 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 ...
6
votes
3answers
3k views

Writing java doc comments for unit test cases

In my opinion, the unit test cases itself serve as a documentation for the code. My company wants me to write detailed java doc comments on top of unit test cases. Is it necessary to do so? Do you ...
6
votes
3answers
3k views

How to document business rules

I am wondering what would be the formal and the most commonly practiced method of documenting business rules? Also how do you document the UI specifications of development artifacts (e.g. Documenting ...
6
votes
5answers
864 views

Open source software with good code documentation to improve design skill [closed]

As I'm trying to get better at designing good software I'm wondering if there are out there good (as in well written) open source software with lot of code documentation that aims to explain details ...