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

21
votes
6answers
2k 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 ...
4
votes
4answers
3k views

job handover checklist [duplicate]

I have resigned my old employer to start a new job, and I need to prepare a handover [documentation to be taken by some new employee that haven't arrived yet, and would be some weeks from when I go to ...
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 ...
14
votes
11answers
1k 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 ...
13
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 ...
22
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 ...
8
votes
6answers
2k views

Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?

One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be ...
6
votes
5answers
480 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 ...
38
votes
14answers
3k 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 ...
10
votes
8answers
509 views

Moving from one man project to team project in the future. What should I be doing now in preparation and what can wait?

To elaborate I am interested in knowing what people think you need to put in place while still a one man project (team source control, documentation, builds etc) and what things don't need to be done ...
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 ...
8
votes
6answers
1k views

How do I document my code? [duplicate]

I'm a hobbyist programmer (with no formal education) looking to start doing small freelance jobs. One of the things that hobbyist programmers can get away with that those with a "real" job can't is ...
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 ...
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 ...
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 ...
11
votes
5answers
7k 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 ...
38
votes
6answers
2k 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? ...
15
votes
8answers
745 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 ...
61
votes
16answers
6k 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 ...
15
votes
5answers
5k 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 ...
13
votes
5answers
8k views

Design documents as part of Agile

At my workplace, we face a challenge in that "agile" too often has meant "vague requirements, bad acceptance criteria, good luck!" We're trying to address that, as a general improvement effort. So, ...
4
votes
3answers
183 views

What could be some pitfalls in introducing a style guide and documentation generating software in a development team?

I'm considering using appledoc, a flavor of Doxygen for use in generating Objective-C code documentation, in order to create documentation for my company's iOS apps. The idea is that a server will ...
3
votes
2answers
21k views

What is the difference between technical specifications and design documents?

What are technical specifications? Are they the same as design documents. If not, what is the difference and some examples?
11
votes
7answers
4k views

Are wikis really appropriate to store documents for software development? [closed]

Everybody knows that well-documented software development leads to success. However, it usually means that not only plain text but also binary content will be involved in the document, such as a UML ...
11
votes
8answers
1k 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 ...
2
votes
3answers
1k views

Writing an (end-) user documentation [duplicate]

I am looking for (common / abstract) templates and examples for the (end user) documentation of software. I especially need something for an "Installation Guide", an "Operation Guide" (operation / ...
12
votes
7answers
845 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. ...
10
votes
6answers
800 views

Are comments considered a form of documentation?

When I am writing small scripts for myself, I stack my code high with comments (sometimes I comment more than I code). A lot of people I talk to say that I should be documenting these scripts, even ...
6
votes
5answers
897 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 ...
2
votes
1answer
207 views

Would you choose a database or a dvcs as storage for a documentation wiki?

I'm about to start coding a documentation oriented wiki, as a pet project. The core features are: Extremely easy grouping of documents per version Markdown syntax (subset of) Multiple authors ...
13
votes
5answers
13k 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 ...
37
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 ...
14
votes
2answers
5k 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 ...
29
votes
8answers
3k 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 ...
7
votes
4answers
479 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 ...
42
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 ...
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 ...
12
votes
4answers
4k 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
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 ...
8
votes
2answers
982 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 ...
6
votes
3answers
959 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 ...
3
votes
4answers
4k views

Creating a coding standards document

I work in a control systems company, where the primary work is SCADA and PLC, along with other control systems stuff. Softwre development is not really something the company does, apart from little ...
20
votes
5answers
917 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 ...
10
votes
1answer
956 views

what kind of online technical documentation system would you recommend? [closed]

the goal is to have an online documentation system, with these major requirements: will be mainly used as an intermediate stage for the final technical docs of all our application (which will ...
9
votes
4answers
976 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
5answers
350 views

Determining the right amount of documentation

Where I currently work the general approach is - avoid documentation as much as possible Only document if a different team will need it just for clarification, I don't mean code-documentation - ...
9
votes
9answers
454 views

Studies on code documentation productivity gains/losses

After much searching, I have failed to answer a basic question pertaining to an assumed known in the software development world: WHAT IS KNOWN: Enforcing a strict policy on adequate code ...
7
votes
6answers
381 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
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 ...
8
votes
5answers
596 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 ...