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
vote
1answer
21 views

Coping with Spring-Security's incomplete documentation [on hold]

I have been a user of core Spring functionality (IOC) for a decade and really appreciate the IOC paradigm. I am also a fan of XML configuration, with limited use of autowiring, as it places all the ...
-2
votes
0answers
56 views

Reading Code Documentation [closed]

I have been studying computer science for a year and a half, and even after 5 programming classes plus my own studies I have yet to understand how does one go about reading source code on github ...
22
votes
6answers
2k views

Explaining new or uncommon syntax in comments [duplicate]

As per the title, should I be explaining syntax that I use in my code when I have a reasonable expectation that a developer looking at my code in the future will not be familiar with it? Short caveats ...
9
votes
1answer
136 views

How to keep code examples in javadocs up to date

I'm working on a small library that provides implementations of basic, well known string metrics. Mostly for my own education. So development happens whenever I've got a bit of spare time. Because of ...
94
votes
10answers
7k views

How to make a large codebase easier to understand for new programmers

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 ...
2
votes
7answers
1k views

Should you use “internal abbreviations” in code comments?

Should you use "internal abbreviations/slang" inside comments, that is, abbreviations and slang people outside the project could have trouble understanding, for instance, using something like //NYI ...
2
votes
0answers
73 views

Best practice for documenting ports/hardware for embedded project? [migrated]

I've recently taken an interest in embedded development and am wondering how most people document their projects. For example: Each pin on PORTE is wired to an LED and is aliased as LEDPORT. ...
64
votes
13answers
9k 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()); ...
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
307 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
485 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
544 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
1answer
446 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
187 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
35 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
80 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
42 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
70 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
294 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
102 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
108 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 ...
4
votes
2answers
975 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 ...
5
votes
4answers
152 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
171 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
159 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
153 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
286 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
42k 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
262 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
1k 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
355 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
175 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
89 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
261 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
559 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
101 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
4k 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
349 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
140 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 ...