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

-4
votes
0answers
28 views

Is there a modern incarnation of the Java Web Start CD-Install page? [on hold]

The Java Web Start Guide used to include a page describing how to make a Web Start application installable from external media, but that page isn't in recent versions of the documentation. Is an ...
-4
votes
0answers
56 views

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

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 ...
3
votes
3answers
167 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 ...
3
votes
1answer
132 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 ...
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 ...
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 ...
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 ...
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 ...
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 ...
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 ...
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 ...
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 ...
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 ...
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
136 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 ...
88
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 ...
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 ...
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 ...
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 ...
5
votes
2answers
426 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
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 ...
-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, ...
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 ...
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 ...
1
vote
1answer
213 views

As an lone, Agile (PXP/PSP) developer what is the proper structure for a formal project post-mortem? [closed]

Question: As an lone, Agile (PXP/PSP) developer what is the proper structure for a formal project post-mortem? Scenario I'm using a PXP methodology (which is a blend of extreme programming and the ...
3
votes
2answers
114 views

How to document a file format specification [closed]

For a project, I need to work with varying types of files from some old games and related software--configuration files, saves, resource archives, and so on. The bulk of these aren't yet documented, ...
-1
votes
3answers
166 views

Has there been any formal proof that documentation in general is incomplete and obsolete to a certain grade? [closed]

I'm a web developer and I'm currently once again in a situation where a partly clueless ops department requires a "complete" documentation required for technical support of our application by a ...
1
vote
2answers
78 views

How to write descriptive conditionals for ifs?

I've gotten into the habit of using excessively descriptive names. In addition, I've also gotten into the habit of creating the conditions for ifs like so: bool user_is_female = user.get_gender() ...
17
votes
4answers
2k views

How to document the high-level structure of a Java program?

Background: My collaborators and I are writing an article for an academic journal. In the course of our research, we wrote a simulation program in Java. We want to make the simulation program freely ...
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. ...
0
votes
0answers
43 views

How would you collect the ideas that needs to be discussed during time [duplicate]

What is the best way of collecting and/or keep tracking of ideas/issues that needs to be discussed in details and during the time? As an example, imagine within the team you're brainstorming about ...
0
votes
1answer
101 views

Documentation required for commissioned software (product) [closed]

The company I work for has commissioned a software company to produce a compliance software for several big companies. As part of our contract it is required of them to provide us with src code and ...
5
votes
4answers
198 views

Keeping documentation / manuals up-to-date in a rapidly changing project

Background I work on a relatively large project (~570 KLOC) in a relatively small team (formerly 5 developers, now 2). Large amounts of code can appear and then vanish in months; for example, a few ...
1
vote
2answers
132 views

How to document self explanatory setter functions? [duplicate]

Often boolean setters are pretty self-explanatory, like setLogErrors($bool). I do see some benefit of providing some additional information in the documentation, in this instance maybe where these ...
0
votes
2answers
49 views

Multiple documentation issues in a single bug

It is clearly a bad practice to incorporate several issues in a single bug. It is not convenient, hard to maintain, difficult to keep track of what is done and what is not, etc. But does all this ...
-2
votes
1answer
160 views

Best practices in Application's flow diagram [closed]

I make web applications, mostly MVC, object oriented and database enabled. I always have trouble going back to project after a few months of release and work again. I don't even remember what I made ...
0
votes
1answer
42 views

Am I allowed to use text(snippets) from the iOS Developer Lib for my documentation?

At the moment, I create a Java-Wrapper for Apples *.pkpass-Files (Passbook). Since I need to parse a JSon-File, I planned to add java doc to every field, so one know what exactly this field is in the ...
0
votes
1answer
89 views

How to organize software document for the same application supporing both iOS and Android

I have to write software project documentation for an application which will support both iOS and Android. Each platform has its specific features and the mobile app design and requirements are almost ...
2
votes
1answer
196 views

Outline for technical software documentation

Say I have a software project for which the technical documentation should include A license document A list of used terminology An introduction about what the software does A short quick-start ...
1
vote
1answer
117 views

Use of # in answers/documentation when referring to methods of a class

When looking through Java documentation or answers for Stack Overflow / programming forum questions, I often see people referring to methods like String#format, Object#clone etc, rather than ...
1
vote
2answers
177 views

Documenting/defining data structures in Python

What is the preferred way to document the contents of and logic behind dynamically generated data structures in Python? E.g. a dict which contains the mapping of a string to a list of lists of ...
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 ...