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

9
votes
3answers
711 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 ...
9
votes
3answers
520 views

What is the connection between literate programming and the semantic web?

I was (casually) researching semantic / ontology based approaches to technical documentation, when I stumbled upon this gem: Literate Programming and the Semantic Web are ideas from different ...
9
votes
5answers
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 ...
9
votes
3answers
2k 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 ...
9
votes
4answers
2k views

How to manage an open source project's documentation? [closed]

I am the creator of a growing open source project. Currently, I'm becoming frusterated trying to figure out the best way to manage documentation. Here are the options I have considered: HTML Website ...
9
votes
1answer
183 views

How to keep code examples in javadocs up to date

I'm working on a small library that provides implementations of basic, well known string metrics. Mostly for my own education. So development happens whenever I've got a bit of spare time. Because of ...
9
votes
1answer
409 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 ...
9
votes
7answers
7k 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, ...
9
votes
3answers
238 views

How to refer to specific areas of code in documentation?

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
9
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 ...
9
votes
5answers
4k 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 ...
8
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 ...
8
votes
6answers
3k 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
5answers
864 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 ...
8
votes
5answers
360 views

How to prevent changes to an internal API from breaking other projects?

We have like 20 - 30 independent modules/solutions. Each of these has about 7 - 10 projects with different classes, components, etc. These are all used internal to our company. Our problem is when ...
8
votes
4answers
30k views

What is an “implementation plan”? [closed]

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
5answers
1k 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
674 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
2answers
2k 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
5answers
1k 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
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
3answers
4k 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 ...
8
votes
2answers
5k views

How to do documentation for code and why is software (often) poorly documented?

There are some good examples of well-documented code out there, such as java api. But, a lot of code in public projects such as git and internal projects of companies is poorly documented and not very ...
8
votes
3answers
374 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
6k 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 ...
8
votes
5answers
2k 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
5answers
320 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
172 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, ...
8
votes
2answers
217 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 ...
8
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 ...
8
votes
1answer
730 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
1answer
3k 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 //...
8
votes
2answers
959 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?
7
votes
10answers
394 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 ...
7
votes
6answers
603 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 ...
7
votes
3answers
6k 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
411 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
3answers
183 views

Is it bad practice to add external links in documentation?

Often I find myself solving bugs by finding the answer on Stack Overflow. Is it bad practice to add a snippet of why I did what I did and then add a link to an article or page from the web?
7
votes
2answers
318 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 ...
7
votes
4answers
1k 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 ...
7
votes
5answers
2k 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
2k 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
2answers
204 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 ...
7
votes
1answer
603 views

Java code documentation in a separate docs file somehow mapped to a source file?

What would be a good alternative to inline Java documentation, i.e. can one have a separate docs file somehow mapped to a java source file? I have never liked huge comment sections littered in code.
7
votes
4answers
398 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
8k 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
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 -...
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
4k views

What information should be in the github README.md?

What information would you expect to see in the github README? Should everything go in the README? i.e. Introduction Installation Versions User Guide Implementation Testing Related Resources Or ...
7
votes
6answers
1k views

How useful are function points? [closed]

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