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

86
votes
12answers
6k views

Should the commit history be used to convey critical information to developers?

During a meeting regarding the rollback of a third-party SDK from the latest version it was noted that the our developers already flagged in the commit history that the latest version should not be ...
-4
votes
0answers
55 views

Where do programmers look for reference/documentation about Java's features/libraries/functions? [on hold]

Rookie programmers learning the language usually use a book or online materials.They are introduced to the language's syntax, common used functions for text processing or math operations. Only a small ...
1
vote
1answer
82 views

Does phpDocumentor tags order matter?

When we document our class, method and/or function with phpDocumentor, is there any specific order I should follow according to the standards? I know it doesn't matter for output the document. Since ...
3
votes
3answers
164 views

Is it misleading to label code as a particular design pattern if it only loosely fits the definition?

Background: I have a rough, but working understanding of ~15 design patterns. It's been my experience using design patterns in my own projects that the resulting implementations usually end up as some ...
1
vote
0answers
33 views

First programming job with few resources to learn from [duplicate]

I recently started my first programming job after working for a couple of years developing websites. This new company focuses on PHP and has had only one developer responsible for the code since the ...
33
votes
3answers
2k views

What roadblocks face the development process in using plain-text markup languages as opposed to, e.g., Microsoft Word? [closed]

I'm currently an intern at a government contractor and am getting the (obnoxiously unavoidable) feeling that Word is the de-facto standard in the software development process. Its binary format makes ...
3
votes
1answer
130 views

Usage of this keyword in constructor chaining?

I am reading msdn documentation for this keyword. They gave three usages for this keyword as follows To qualify members hidden by similar names To pass an object as a parameter to other methods To ...
14
votes
6answers
4k views

Git-friendly spreadsheet format? [closed]

We're trying to move our project documentation process from Google Documents to a set of self-hosted Git repositories. Text documents are Git-friendly enough, since we usually do not need any fancy ...
4
votes
1answer
283 views

How to move php documentation closer to standards?

I have an large php project. I used to document it with NaturalDocs, but I didn't include the documentation generation in the build process for a long time ( years ). I recently started using ...
66
votes
14answers
8k views

How should I remember what I was doing and why on a project three months back?

I was working on a project three months back, and then suddenly another urgent project appeared and I was asked to shift my attention. Starting tomorrow, I'll be heading back to the old project. I ...
0
votes
2answers
136 views

The source is the documentation - part 1 [closed]

Searching the specification for the btrfs file system i stumbled once more over the catchphrase: "The code is the documentation". This implies that changing the code changes the specification. Does ...
3
votes
7answers
909 views

taking notes while reading source code of large projects [closed]

Whenever we start reading a big project source code it's often necessary to note down the calling chains and notes that reason why a specific code pattern was chosen, for example. I found primitive ...
3
votes
7answers
1k views

Writing better timesheet [closed]

Recently, my company started to require us to fill out a monthly timesheet, writing down everything you do in office. A timesheet contain 29-31 days, depends on the number of days of the month. I ...
1
vote
1answer
129 views

How to make Doxygen documentation that helps in understanding the code?

So a few years ago I came across a statement that most of the Doxygen generated documentation out there is quite bad. "Bad" in the sense that defies the purpose of documentation and doesn't help in ...
10
votes
5answers
2k views

Better way to train new hires [closed]

The team I currently am part of experiences fairly high turnover, with members typically moving to different projects within the same company. Currently our "training" for new members is to pair them ...
0
votes
3answers
90 views

Seeking advice writing functional requirements [duplicate]

I inherited a project that I've been maintaining for approximately a year now. The project primarily revolves around performing various financial calculations for the end user. It's roughly 100,000 ...
-1
votes
2answers
113 views

How can I refer to the standard language documentation less? [closed]

When I code in a language (ex. Ruby) I find myself looking up things in the standard ruby docs quite a bit. Array#include? for example (I had tried Array#contains?), method names I feel I shouldn't ...
0
votes
0answers
37 views

Is this synchronization required in service onCreate method?

Below is a sample code i captured from android doc Per service instance onCreate will be called only once. Ref: here and here The synchronization and singleton doesn't make any sense to me in this ...
0
votes
2answers
123 views

Referencing StackOverflow questions in comments [duplicate]

Often when coding I'll get stuck on a particularly tricky problem and will go about searching for a solution. More often than not this leads me to a StackOverflow question that provides a full or ...
44
votes
12answers
6k views

Is there any logical reason to auto-generate code documentation? [closed]

Automatic documentation generation can be done with a variety of tools, GhostDoc being one of the more prominent. However, by definition, everything it generates is redundant. It takes a look at ...
162
votes
15answers
27k views

What's wrong with comments that explain complex code?

A lot of people claim that "comments should explain 'why', but not 'how'". Others say that "code should be self-documenting" and comments should be scarce. Robert C. Martin claims that (rephrased to ...
18
votes
1answer
1k views

When systems get larger and larger, how do you keep a global understanding of your system? [duplicate]

Today I realized painfully that for some decisions you need a good overall understanding of the system. Otherwise, the risk is too high that your assumption turn out to be wrong. Imagine that you are ...
11
votes
4answers
619 views

How to document and teach others “optimized beyond recognition” computationally intensive code?

Occasionally there is the 1% of code that is computationally intensive enough that needs the heaviest kind of low-level optimization. Examples are video processing, image processing, and all kinds of ...
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 ...
1
vote
1answer
129 views

Changelog Management [closed]

I'm currently developing a WinForm application. In order to inform the client about the improvements and corrections made during the last version, I would like to manage and display a changelog. I ...
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?
4
votes
6answers
2k views

What should I include in my class documentation header

I'm looking for informative class documentation format for my Entity, Business Logic and Data Access classes. I found following two formats from here Format 1 ...
9
votes
1answer
215 views

Implied precision of floating-point functions

While reviewing another programmer's implementation of a function to calculate the normal distribution CDF, I made a suggestion to either replace the entire implementation with Python's built-in ...
3
votes
1answer
133 views

When to declare @throws with a Scala annotation - abstract parent or concrete implementation?

In this StackOverflow question I asked about the behavior of the @throws annotation in Scala. Now that I understand how it works I want to ask about best practices with using it. Here's a repost of my ...
1
vote
0answers
29 views

New project from a third party and documentation [duplicate]

I'm going to become the custodian of an iOS project developed by a third party and my boss just asked me for a list of documentation that I think we should be asking the third party for when they hand ...
1
vote
2answers
156 views

How should I document a multi-tier application?

I have to create a documentation structure for a legacy application, and I'm not sure of how to organize it. Documentation goals: List of use-Cases Program flow for each of the use cases. ...
1
vote
2answers
92 views

How specific should be an interface about its implementation details?

Perhaps I should have picked a better title, but anyway... Basically what to do with two or more implementations that have the same public interface, but they are meant for slightly different ...
0
votes
1answer
47 views

Referencing official documentation in source-code documentation

What are your preferences for referencing official documentation (like a white paper) for an algorithm from comments in the code that implements it? I'm trying to decide between two methods, as ...
4
votes
3answers
581 views

Is it Typical for Large Software Companies to Not Document or Refactor Code? [closed]

I have begun working at a large software company and was assigned to a project that is over a million and a half lines of code. It's part of a program suite that is sold to clients (not an in-house ...
5
votes
2answers
421 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 ...
2
votes
5answers
185 views

How viable is to create a mini documentation inside the source code

So, I work as a developer. We are a small team. The majority of the people (everyone except the project manager and the senior developer) are still in university. We have very flexible work hours, ...
3
votes
5answers
577 views

How do you keep track of the meaning of your SQL fields?

The more SQL fields I add to my tables and the more primary/foreign keys I add the more I lose the overview for specific fields for certain scenarios like Get/Add/Delete/Update data. I use SQL ...
3
votes
2answers
192 views

Is it customary for software companies to forbid code authors from taking credit for their work? do code authors have a say?

The company I work for has decided that the source code for a set of tools they make available to customers is also going to be made available to those customers. Since I am the author of that source ...
0
votes
1answer
174 views

Your thoughts on Best Practices for Scientific Computing? [closed]

A recent paper by Wilson et al (2014) pointed out 24 Best Practices for scientific programming. It's worth to have a look. I would like to hear opinions about these points from experienced programmers ...
1
vote
1answer
55 views

What does backup procedures and troubleshooting guidelines mean for a system

I am writing the documentation for a piece of software which I have made but I don't understand what it means in some aspects. It asks me to write about backup procedures but what exactly does this ...
8
votes
6answers
517 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 ...
5
votes
3answers
363 views

Should I follow an open source project's documentation patterns even if they are bad?

I've considered making modules and the like for various languages and other open source things. Where documentation is not specified but rather is communal de facto standard or entirely ad hoc; should ...
-2
votes
1answer
47 views

Where can I find better designed nginx documentation? [closed]

Actually I have a sub-question here:"Is Nginx official documentation opensourced?" Nginx is a good software, but I found its official documentation(http://nginx.org/en/docs/ really hard to read, ...
1
vote
3answers
124 views

How to consider the login function collecting requirements of an application? is it a user requirement?

I am working on an application that expected to the user logs in when the application is started (as for example it is in Skype: the user open the application and appear to him a login mask when he ...
0
votes
0answers
16 views

Scala/SBT - Documenting Configuration Change for Releases

I'm trying to collect different ways of managing configuration across multiple environments. I have a requirement to document configuration changes for the deployment plan. Dev values are defaults in ...
12
votes
9answers
788 views

Code Documentation First?

Has anyone ever tried creating a complete code documentation first, before actually writing the code? I was thinking about this earlier because I thought it would help to write a concrete interface ...
0
votes
3answers
154 views

What goes within the Architecture Overview of a Design Specification?

I have designed an management system for a medical practice and I am writing the design specification and I am kind of stumped by what to write for a section. It asks for me to write about the ...
3
votes
3answers
798 views

Are there any standards for preparing a user manual of electronic device? [closed]

Are there any standards for preparing a user manual of electronic device? I am trying to prepare a manual for a device. However, I could not find any format. If I find, I will take this as guide for ...
0
votes
1answer
526 views

Are there differences between Functionality and Functional Requirements [closed]

I'm writing some documentation in a project in a tool. In this tool of mine, and write in specific area, I have here use Case, Business Rule, N-Diagram Types, and Functionality and Functional ...
4
votes
3answers
1k views

What wiki/document system do you recommend for knowledge-management? [closed]

I'm founder of a web-site called Now.in. I wrote all programs by my-self at first. And we are going to run a start-up company. More people will soon get involved. Some know-how/overviews only exist in ...