Questions tagged [documentation]

Software documentation is written text that accompanies computer software. It explains how the software operates, how to install it, how to use it, and other resources for help.

Filter by
Sorted by
Tagged with
34
votes
6answers
5k 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 ...
82
votes
13answers
12k views

Can commented-out code be valuable documentation?

I wrote the following code: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); ...
236
votes
16answers
44k 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
11answers
2k 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
2k 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 ...
7
votes
4answers
12k 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 ...
47
votes
20answers
6k 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 ...
12
votes
6answers
5k 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 ...
16
votes
6answers
13k 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 ...
155
votes
50answers
18k views

My boss wants a narrated line-by-line English explanation of our code

I have been specifically asked to give line by line (or as appropriate - for example, image by image, etc.) explanation or commentary which my boss wants to be able to read and follow. Since he is ...
47
votes
14answers
5k 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 I'...
86
votes
17answers
43k views

Do TODO comments make sense? [closed]

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 ...
10
votes
5answers
5k 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
5answers
2k 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 ...
22
votes
8answers
2k 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 ...
72
votes
14answers
9k 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 ...
37
votes
2answers
163k 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?
62
votes
10answers
23k 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 ...
41
votes
6answers
3k 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? ...
25
votes
5answers
32k 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, ...
12
votes
7answers
987 views

Documentation degrading - how to deal with it?

Important: we have no issues whatsoever with source code documentation. This belongs to regular code audit and is kept up to date. Our problem is with developers documentation (or, "external" if you ...
15
votes
5answers
4k 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 ...
49
votes
8answers
8k views

Should generated documentation be stored in a Git repository?

When you use tools like jsdocs, it generates static HTML files and its styles in your codebase based on the comments in your code. Should these files be checked into the Git repository or should they ...
15
votes
8answers
2k 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 ...
19
votes
4answers
3k 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 ...
11
votes
4answers
3k 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 ...
4
votes
3answers
295 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 ...
21
votes
6answers
4k 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 ...
10
votes
6answers
975 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 ...
8
votes
5answers
4k 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 ...
4
votes
6answers
773 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 ...
2
votes
3answers
2k 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 / ...
13
votes
7answers
28k 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 ///------------------------------...
7
votes
5answers
3k 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 ...
6
votes
5answers
1k views

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

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 ...
4
votes
3answers
399 views

Should code comments explain the control flow?

Should comments explain how the application control flow works? For example, the relationships between classes, how this function is used by other functions, and what we are trying to do with these ...
104
votes
10answers
9k views

How to make a large codebase easier to understand

Suppose that I am developing a relatively large project. I have already documented all my classes and functions with Doxygen, however, I had an idea to put a "programmer's notes" on each source code ...
94
votes
12answers
7k 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 ...
18
votes
5answers
14k 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 ...
14
votes
4answers
15k 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 ...
43
votes
7answers
4k 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
5answers
18k 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
4answers
787 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 ...
14
votes
6answers
3k views

Why do so many libraries have no/poor documentation? [closed]

In a similar vein as the How can open source projects be successful without documentation about their design or architecture? question, I'm curious: Why are so many libraries so lacking in end user ...
13
votes
8answers
815 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 ...
11
votes
4answers
730 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
5answers
427 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 ...
11
votes
1answer
1k 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 ...
11
votes
2answers
3k 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 ...