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
282 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
3answers
529 views

using a wiki for requirements

I'm looking into ways of improving requirements management. Currently, we have a Word document published on a Web site. Unfortunately, we cannot (to my knowledge) look at changes from one revision ...
8
votes
5answers
889 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
322 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
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
5answers
302 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
4answers
1k 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
7answers
4k 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
1answer
507 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
10answers
3k views

As a programmer, what would you use a personal Wiki for? [closed]

Do any programmers out there keep a personal wiki? Either locally or online. What do you use your wiki for? or what might you use one for? I was thinking of starting a personal wiki as a place to ...
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
381 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
4answers
4k 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 ...
7
votes
4answers
16k 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 ...
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
4answers
318 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
1answer
3k 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
193 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
1answer
782 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
4k 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
480 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
2answers
596 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
416 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
527 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
383 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
592 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
482 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
960 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
320 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
5answers
235 views

Should documentation be a company policy or every programmer's responsibility?

I have been struggling lately with the whole subject of documentation at my current position. I am at a point in my programming career in which I feel I have just been birthed into the whole world of ...
6
votes
4answers
732 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
507 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
5answers
417 views

Maintaining good form while learning new technologies

I find that I have to learn new technologies fairly regularly as a contractor in order to keep competitive. However, I also find that (not only, but especially) in these circumstances, I tend to end ...
6
votes
2answers
279 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
363 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
908 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 ...
6
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 ...
6
votes
2answers
2k views

Backend programming portfolio

For most of my development years I have been a Java backend developer, mostly for web applications. Usually for regular jobs I have described my duties in previous ones during the interview, expanding ...
6
votes
2answers
220 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
2k 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
2answers
923 views

How does one read RFCs and similar documents?

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 ...
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 ...
6
votes
2answers
176 views

Is it unreasonable to write user documentation in the style of a technical book?

Tell me if this sounds familiar: something something something... as seen in figure 1-1 on the next page... It's in practically every book I've ever read about programming. So when I was ...
6
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 ...
6
votes
1answer
293 views

Does MSDN follow documentation conventions for .NET, and if so is it publicly available?

While browsing the MSDN documentation for the .NET Framework Class Library (FCL) I've always been amazed by how consistent and fully documented it is. It's a constant companion when developing .NET ...
6
votes
1answer
140 views

How to change documentation expectations from “risk management” to a “project risk”

We are trying to introduce some agile concepts to the business folks but one of our biggest hurdles is their expectations for documentation - the quantity, the authorship/ownership of the documents, ...
6
votes
4answers
3k views

Software testing automation documentation

What document types could be used when describing software testing automation (on any phase, automation planning, test design, implementation, reporting)? Is there any standard types of documents? If ...