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

-2
votes
0answers
50 views

What documentation should we include in our source code? [closed]

What should we be keeping in our source code's docs? Should they just be brief descriptions of what each function/method's intentions are, or should they be full-blown reference information containing ...
5
votes
3answers
506 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
417 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
164 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
31 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
69 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
33 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
56 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
96 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
568 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
140 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
126 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
125 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
283 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
36k 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?
2
votes
1answer
156 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
726 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
181 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
169 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
84 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
246 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
541 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 ...
4
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
87 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
347 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
138 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 ...
182
votes
16answers
30k 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
119 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
64 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
83 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() { ...
90
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 ...
1
vote
1answer
138 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 ...
3
votes
3answers
177 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 ...
33
votes
3answers
2k views

What roadblocks face the development process in using plain-text markup languages as opposed to, e.g., Microsoft Word? [closed]

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 ...
3
votes
1answer
162 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 ...
16
votes
6answers
5k 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 ...
4
votes
1answer
384 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 ...
67
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 ...
0
votes
2answers
149 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 ...