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

151
votes
29answers
9k views

Humor in Documentation

Is a small amount of lighthearted wording or humor acceptable in source code documentation? For example, I have an algorithm that has a message hop around a graph (network) until its path forms a ...
70
votes
13answers
3k views

What are examples of comments that tell you why instead of how or what? [closed]

First of all, in this question I'd like to stay away from the polemic on whether source code commenting is good or bad. I'm just trying to understand more clearly what people mean when they talk about ...
65
votes
15answers
8k views

I'm going to quit my job because of our platform: how can I leave a productive explanation of this? [closed]

I'm planning on leaving my current job because we're locked into using Blub, with an enterprise Blub framework and a Blub-level web server, on mediocre shared hosting. My coworkers are friendly and my ...
57
votes
16answers
4k views

Do TODO comments make sense?

I am working on a fairly big project and got the task to do some translations for it. There were tons of labels that haven't been translated and while I was digging through the code I found this ...
55
votes
17answers
4k views

How to deal with tautology in comments?

Sometimes I find myself in situations when the part of code that I am writing is (or seems to be) so self-evident that its name would be basically repeated as a comment: class Example { /// ...
45
votes
20answers
4k views

Should you write good documentation and clean code to increase the “Bus Factor”?

One of the main goals of software development companies is to increase their Bus factor This is also advocated in a talk that was organized by Google. That means that you should code and document ...
41
votes
7answers
3k views

How do you keep track of what classes and functions your team has written?

When working on code, I face many of the same challenges that my teammates do, and I have written some helpful functions and classes, and so have they. If there is good communication, I'll hear about ...
39
votes
6answers
2k views

“I”, “We”, or Neither in code documentation

I find myself writing (hopefully) helpful comments in code (C++) documentation of the type: The reason we are doing this is... The reason I use "we" instead of "I" is because I do a lot of academic ...
38
votes
6answers
1k views

What should I do to leave a job professionally? [duplicate]

Given that the current employer knows and has been given appropriate notice ahead of time, how can a programmer make a clean job transition from his old job? What things should the programer consider? ...
37
votes
14answers
2k views

What's with the aversion to documentation in the industry?

There seems to be an aversion to writing even the most basic documentation. Our project READMEs are relatively bare. There aren't even updated lists of dependencies in the docs. Is there something ...
37
votes
12answers
2k views

Documentation in OOP should avoid specifying whether or not a “getter” performs any computation?

My school's CS program avoids any mention of object oriented programming, so I've been doing some reading on my own to supplement it -- specifically, Object Oriented Software Construction by Bertrand ...
35
votes
18answers
2k views

How can I improve my technical writing?

Writing documentation is part of programming, and writing well is part of what makes the documentation useful. So, what are some hints or guidelines for good writing in the technical realm? What are ...
30
votes
2answers
1k views

Why aren't plain-text markup languages (like LaTeX or Markdown) more popular in the software development process?

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 ...
29
votes
3answers
871 views

Origin of “Readme”

When did people start writing Readme files? It seems that pretty much all programs have this file, regardless of the format. Is there any documented first use of this document?
28
votes
8answers
2k views

Is there such a thing as having too many private functions/methods?

I understand the importance of well documented code. But I also understand the importance of self-documenting code. The easier it is to visually read a particular function, the faster we can move on ...
23
votes
13answers
2k views

When do you start documenting the code?

Some friends and I recently started a medium-size project. We already covered the design part (at least the first attempt) and now we are moving into coding. We already have implemented some objects ...
21
votes
4answers
916 views

Is BDD actually writable by non-programmers?

Behavior-Driven Development with its emblematic “Given-When-Then” scenarios syntax has lately been quite hyped for its possible uses as a boundary object for software functionality assessment. I ...
20
votes
6answers
1k views

Methodology for documenting existing code base

I work as part of a team on an existing application that has no inline documentation, nor does it have technical documentation. As I've been working on various bug reports on the application, I've ...
19
votes
6answers
2k views

Old programmer disappeared. About to hire another programmer. How do I approach this? [closed]

After spending over one year working on a social network project for me using WordPress and BuddyPress, my programmer has disappeared, even though he got paid every single week, for the whole period. ...
19
votes
8answers
1k views

Should you document everything or just most?

It seems a bit of a controversial subject to document everything, including the "JavaBean" syntax of getters and setters for fields: People say its needlessly long and repetitive breaking DRY (don't ...
19
votes
5answers
794 views

How-to convince company to start documenting for legacy software [duplicate]

It has been less than a year since I joined my current company. Their majority of sales have come from a single product that has been alive since the last 10 years. However, there is minimal (if at ...
18
votes
12answers
801 views

What makes documentation good? [duplicate]

I need to write documentation for several projects I worked on. I was wondering what, according to your experience, makes documentation useful and complete. What part should I include, how deep should ...
18
votes
3answers
13k views

What javadoc equivalents do you use in .net? [closed]

Java developers use Javadoc in order to write inline documentation in their comments. What are the alternatives for .net - specifically c# and VB.net that people actually use in real world projects?
17
votes
4answers
827 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 ...
15
votes
6answers
1k views

Can you claim that your product is fit for purpose when it uses OSS software which does not guarantee it?

I am working on a product for a client that must be valid and fit for purpose. It's built on a LAMP stack (PHP/Cake), so there's GPL, MIT, PHP, APACHE licenses: "AS IS" BASIS, WITHOUT WARRANTIES ...
15
votes
6answers
478 views

Are unit tests really used as documentation?

I cannot count the number of times I read statements in the vein of 'unit tests are a very important source of documentation of the code under test'. I do not deny they are true. But personally I ...
15
votes
8answers
601 views

What are technical writing principles? [duplicate]

As a programmer, technical writing is an important skill to me. I get a lot of fun from it. I also learned from some good technical articles and books. What I need are technical writing principles or ...
15
votes
5answers
4k views

What does your Technical Documentation look like? [duplicate]

I'm working on a large project and I would like to put together some technical documentation for other members of the team and for new programmers joining the project. What sort of documentation ...
15
votes
7answers
735 views

How can Scrum be adapted to an academic environment?

I'm currently working with a professor at my university to develop new curricula for the Software Engineering and Capstone Design courses offered in my college. Up until recently, both courses used ...
14
votes
11answers
841 views

What should you leave behind for your successors?

Assume that you're a sole developer leaving a job. What kind of information/material, outside of the code itself, should you create and leave behind for your replacement? An obvious answer is ...
14
votes
4answers
836 views

Documenting mathematical logic in code

Sometimes, although not often, I have to include math logic in my code. The concepts used are mostly very simple, but the resulting code is not - a lot of variables with unclear purpose, and some ...
14
votes
5answers
1k views

Is a well written documentation a good enough reason for learning a programming language?

I am learning Python currently which wasn't part of my college curriculum. I was asked in an interview why I chose Python and I replied that it is easy to learn and the documentation is very well ...
14
votes
5answers
2k views

How are minimum system requirements determined?

We've all seen countless examples of software that ships with "minimum system requirements" like the following: Windows XP/Vista/7 1GB RAM 200 MB Storage How are these generally determined? ...
13
votes
6answers
496 views

Is saying “JSON Object” redundant?

If JSON stands for JavaScript Object Notation, then when you say JSON object, aren't you really saying "JavaScript Object Notation Object"? Would saying "JSON string" be more correct? Or would it be ...
13
votes
2answers
3k views

What standard superseded 830-1998?

I have been looking into how to document software projects more formally, and I have learned about IEEE 830-1998: Recommended Practice for Software Requirements Specifications. However, as you can ...
13
votes
4answers
272 views

Are there efforts to build a collaboratively edited HTML/JS/DOM reference?

W3Schools has a reputation of being incomplete, sometimes incorrect, and ridden with advertising; still, when looking to look up some things or link to documentation when answering a SO question, it ...
13
votes
5answers
10k views

Fastest way to document software architecture and design [closed]

We are a small team of 5 developers and I'm looking for some great advices about how to document the software architecture and design. I'm going for the sweet spot, where the time invested pays off. I ...
12
votes
11answers
1k views

Does searching documentation and samples look bad? [duplicate]

I am starting a new job in a company with many developers and media people, the layout of the place is open with computers around a skinny oval, I have worked in small teams and programming embedded ...
12
votes
6answers
728 views

Why do so many libraries have no/poor documentation?

In a similar vein as the Why do many open source projects have no documentation about their design or architecture? question, I'm curious: Why are so many libraries so lacking in end user ...
12
votes
5answers
1k views

Do you create a design with UML before you start? [duplicate]

Possible Duplicate: How often do you use Formal UML? I'm currently following a study UML called UML Fundamentals. While studying, I wondered if companies even bother creating system ...
12
votes
8answers
646 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 ...
12
votes
5answers
821 views

What are the deliverables to give to the client for a web application ?

I have completed a web application which is basically developed in PHP and is just another regular web application. Usually when I deliver the final production release I just handover the code ...
12
votes
6answers
2k 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 ...
12
votes
7answers
754 views

Should a design document contain a discussion of the pros/cons to a given design or should it focus on facts and rationale?

I'm currently in the process of updating a design document so that it is correct and up-to-date for future developers. Currently, the document focuses on only the facts, presenting how the design is. ...
12
votes
6answers
4k views

Software to organize and maintain project documentation, specification? [closed]

I'm looking for software to organize and maintain projects internal documentation, specification, requirements, etc. Currently we store all documentation as lots of MS Word DOC files in a source ...
12
votes
4answers
3k views

Writing Acceptance test cases

We are integrating a testing process in our SCRUM process. My new role is to write acceptance tests of our web applications in order to automate them later. I have read a lot about how tests cases ...
11
votes
6answers
627 views

Does it make me a bad programmer if I dislike the Agile methodology? [closed]

I like the small iterations. I like the unit tests. I like code review. What I don't like is the starting off with little or no documentation. Am I alone in this? Do I simply have a ...
11
votes
7answers
719 views

How can I document someone else's past work?

We're in a bad situation of having very little documentation on customization our past workers made to a business critical system. Lots of changes were done to Crystal Reports, database entities, and ...
11
votes
8answers
961 views

How much documentation is enough?

How much technical (for future developers) documentation is enough? Is there a ratio between hours coding and hours documenting that's appropriate? Papadimoulis argues that you should produce the ...
11
votes
5answers
5k views

Writing a Software Requirement Specification

I have a few questions about writing a specification and they are: When we write a software specification, under the topic "User requirements definition" we have to specify the "Functions" and ...