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
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
293 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
923 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
337 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
305 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
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
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
1answer
548 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
4k 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
385 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
18k 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
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
4answers
326 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
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 ...
7
votes
1answer
4k 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
197 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
854 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
496 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
1k 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
636 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
533 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
384 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
615 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
515 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
979 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
6answers
341 views

Do you write Documentation in a language other than English?

A couple of months ago I moved to Germany. Taking some projects on my own, I've recently had the opportunity to develop with a company-based framework, that was very well documented, but in German. My ...
6
votes
4answers
324 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
236 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
753 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
418 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
292 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
364 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
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
223 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

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
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
1k 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
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 ...
6
votes
2answers
180 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 ...