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

-1
votes
1answer
56 views

What do you call the stuttering type of documentation?

I often find "documentation" like the following (it's really common in Java for some reason): /** * @param constraint The constraint to set. */ public void setConstraint(Constraint constraint) { ...
3
votes
2answers
673 views

How do you document your large projects? [closed]

We've currently got a small team of programmers (3 people) but are expecting to add more soon and are starting to keep documentation on things that need to be interacted with a lot, or reusable ...
-2
votes
0answers
35 views

Appropriate documentation for a small scripting project? [on hold]

I have a client that wants me to write a small scripting application. Comparing a series of text files, outputting the resulting differences, stuff like that; about an 80 hour project from beginning ...
35
votes
9answers
2k views

Can non-IT people handle a wiki? [closed]

My company is looking to improve their market research data management. Current data management style: "Hey Jimbo, where's that picture of our WhatZit 2.0? "yeah I remember that email about that ...
5
votes
6answers
297 views

Hyperlinked, externalized source code documentation

Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code, rather than as a separate document? Given the expansive ...
8
votes
2answers
1k 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 ...
9
votes
4answers
3k views

Prepare source code handover plan [closed]

Our company is about to acquire a source code of a huge product. What are thing to take into consideration when the handover starts, to make sure we have everything and be capable to maintain that ...
9
votes
3answers
229 views

How to refer to specific areas of code in documentation?

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
9
votes
4answers
482 views

Should we be looking out for lying code?

This is referring to a discussion in an answer and the comments of this question: What's with the aversion to documentation in the industry?. The answer claimed that "code can't lie" and thus ...
4
votes
3answers
165 views

Is there a difference between the quotes in `help',``help“, 'help' and ”help"?

Sometimes I find in the source code files comments have quotation marks like these ,notice the ` : `help' ``help" For example, these are comments from GNU cat source code file, cat.c: /* Plain ...
5
votes
3answers
521 views

How to document events?

Code documentation is usually related to a piece of code, be it small (method-level) or larger (class- or namespace-level). However, it is always about the inputs and the outputs of that piece of ...
23
votes
4answers
1k 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 ...
5
votes
2answers
423 views

Java code documentation in a separate docs file somehow mapped to a source file?

What would be a good alternative to inline Java documentation, i.e. can one have a separate docs file somehow mapped to a java source file? I have never liked huge comment sections littered in code. ...
11
votes
5answers
2k views

Software Manager who makes developers do Project Management

I'm a software developer working in an embedded systems company. We have a Project Manager, who takes care of the overall project schedule (including electrical, quality, software and manufacturing) ...
6
votes
2answers
173 views

Is there something peculiar to Matlab or Mathworks that supports so much “undocumented” code?

I've been drilling into a lot of Matlab recently trying to interface with an in house algorithm engineer's work to modularize it for use in a test bench outside his suite of applications. I've come ...
0
votes
0answers
32 views

Is listing Types in documentation a code smell

I'm documenting a ruby application and looking closely at YARD. I like the increased structure provided over RDoc, but I'm unsure about the Type declaration. In YARD, you can do something like ...
2
votes
1answer
72 views

How to write proper documentation for references in a docblock? [closed]

I am adding documentation to PHP code using the phpDocs tool: /** * This is a summary * * This is a description * * @use This function is called here and here */ function doSomething(){ } I am ...
1
vote
1answer
37 views

What information should go into file-level document block?

I primarily develop for Node.js. I got into a habit of putting a file-level docblock into all of my .js files. It looks something like this: /** * project-name * * Licensed under the BSD-3-Clause ...
1
vote
1answer
60 views

Documenting MVC JSON API

I've got an MVC5 application that we're using an a JSON API for various clients (mobile apps, other web applications, etc.) as well as a traditional web application. Controller actions that return ...
3
votes
3answers
292 views

How to be productive as an infrequent programmer? [closed]

My current day job is mostly project management and client liaison work, but I sometimes get involved in actual coding. I do this either because I have a clear vision of what I want the result to look ...
4
votes
3answers
98 views

When should “should” be used in documentation? [duplicate]

I was just reading http://lasagne.readthedocs.org/en/latest/modules/layers.html and wondering about some documentation style questions. One of them was the use of the word "should". For example: ...
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 ...
0
votes
0answers
106 views

Interactive help in a statically-typed language with overloading

One of the nice features of IPython is that I can inspect a function. In [1]: def inc(x): ...: """Increments a number""" ...: return x+1 ...: In [2]: inc? Type: function ...
3
votes
2answers
718 views

How should I annotate, that a class is immutable in Java?

I recently stumbled upon how useful immutable objects are and that e.g. if you pass elements to a constructor and your class should be immutable, you have to copy these elements if they are not ...
8
votes
3answers
1k views

How does one read RFCs and similar documents? [closed]

RFC: Request for Comments (RFC) is a memorandum published by the Internet Engineering Task Force (IETF) describing methods, behaviors, research, or innovations applicable to the working of the ...
4
votes
4answers
147 views

What Type of Report or Documentation to Expect from my Programmers

First, I am not a programmer nor do I have any programming experience. I am an entrepreneur that had a website idea and hired programmers to custom build it. It has been going on for the last one year ...
15
votes
7answers
1k 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 ...
7
votes
5answers
170 views

Do you have any team guidelines regarding exceptions? [closed]

My team recently inherited a project from a team where the amount of developers dropped so low they had to offload some work. One of the projects we inherited was a project littered with nested code, ...
2
votes
2answers
142 views

Agile Scrum - Importance of requirement gathering and documentation and suggestions to improve

We are using agile scrum methodologies for developing and maintaining a product. Since we are a product company, we do not work with customer directly on day to day basis, but instead communicate with ...
1
vote
1answer
135 views

How can I find what Resources a Java EE container provides?

How can I find what "Resources" a Java EE container provides? Can I discover this programmatically, or is there documentation I should refer to? (Note that the Java EE tutorial is vague on this ...
5
votes
5answers
284 views

Should documentation be a company policy or every programmer's responsibility? [closed]

I have been struggling lately with the whole subject of documentation at my current position. I am at a point in my programming career in which I feel I have just been birthed into the whole world of ...
5
votes
2answers
39k 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?
3
votes
1answer
199 views

How do I write a REStful API's functional specifications?

I've been looking for answers about writing functional specifications for a software for a while now but I can't seem to find an answer to my specific case. I think I understand the difference ...
0
votes
3answers
935 views

Who should write the Technical Design Document? The BA or the Developer? [closed]

I work as a Snr. BA in a large Manufacturing company and I've just implemented a new Requirements Management Process. We have a large range of internal developers who in the past have never been ...
2
votes
1answer
252 views

How do tools facilitate writing functional specifications?

C2 wiki on functional specifications suggest that this can be facilitated by tools, how? A Functional Specification is a list of demands and constraints intended to describe a product to be ...
2
votes
3answers
170 views

Documenting intent Vs knowledge

It is said you should document the intent of your function or class which I agree with. However recently this line became a little bit blurred when I was wanting someone to document why this ...
5
votes
6answers
1k views

What is the best way to prove that in-code documentation is greater than extensive external documentation?

What is the best way to prove to my boss that in code documentation is greater than extensive external documents containing documentation and screenshots of code/ui? We have a group in the company ...
4
votes
1answer
88 views

What is the origin of the phrase “extirpated as a potential munition”

I recently came across this statement in the Perl documentation: extirpated as a potential munition derived from the sentence: "Creates a digest string exactly like the crypt(3) function in the ...
1
vote
3answers
252 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 ...
4
votes
1answer
551 views

How can the process of creating and maintaining documentation be improved?

I know it's a very subjective question , but this is one section of Software Engineering wherein I haven't seen any improvement in terms of how we can do it in a better way. I guess every programmer ...
5
votes
1answer
2k views

Does doxygen support templates for the HTML output?

I've documented my code for doxygen, but I don't want the default HTML it gives. I know I can customize it by providing custom CSS, headers, footers, etc. (like GNOME does), and how I can add common ...
1
vote
0answers
94 views

UML diagram for SSIS process

I'm trying to do some technical documentation and would like to include some diagrams to better explain the processes in the system. The process I'm currently trying to describe is the following: ...
1
vote
2answers
3k views

How do I write a software product definition?

I would like to learn how to write a software product definition. Therefore I am looking for online materials or books which would help me to learn more about this topic. I would like to learn, for ...
11
votes
3answers
348 views

Writing High Quality Software Proposals [closed]

I've been reading over some proposals for software projects recently and I'm a little concerned by what I've seen. Often I feel that proposals have been rushed and/or poorly thought out. It's very ...
-2
votes
3answers
139 views

Affecting culture as a newly hired developer [closed]

I've been in my first professional position for about six months now, and so I am hitting what I suppose is the pretty typical moment: Naievely perhaps, I think there's a lot of cultural baggage ...
185
votes
16answers
31k 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 ...
3
votes
3answers
6k views

What is the definition of user classes, with respect to software use?

I'm writing the Software Requirement Specification document for a piece of software that I am developing. A part of the SRS is the identification of the user class. Can somebody please give or refer ...
5
votes
2answers
121 views

peer review code documentation [closed]

We all know that code reviews are generally a good practice, but what about reviewing documentation? Many devs that I work with will put up wiki pages, javadocs, etc, but most of the time, unless ...
1
vote
1answer
68 views

Documentation of interfaces

I know how to document a function: /** * Prints a greet message to the web page */ function greet() { echo "Hi!"; } Or describe the usage of a variable: /** * @type string $name The user's ...
0
votes
3answers
84 views

Defining resource allocation in method documentation

I want to write a library with "no resource leak guarantee" feature. So I shall know whether each method allocates any resource or not. It may change the code. For example: void foo() { ...