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

0
votes
2answers
51 views

The best practice for writing of examples

I have written some projects. I try to annotate or comment all possible (hard to say if correctly toward clean explaining). I would like to write documentation for it, but I have problem with ...
3
votes
0answers
59 views

How much static analysis history should a company keep?

Supposing you work in a very large global company with lot of code at all levels (e.g. from embedded to mobile platform application code), and projects can last anything between 6 months to 5 years... ...
0
votes
1answer
58 views

Is there any common way to document libraries used in a Software Product? [closed]

One of our clients asked us for: Overview of the libraries we are using in a format which is common. List the libraries along with the licenses. The reason behind this requirement is: ...
5
votes
1answer
52 views

How can I better document these data relationships/transformations?

I'm working on a project that uses RxJS to perform data transformations on varying sources of data, and I'm in the process of writing some documentation for it. I want to find an effective way to ...
21
votes
1answer
2k views

Why does the documentation on some languages say “equivalent to” rather than “is”?

Why does the documentation on some languages say "equivalent to" rather than "is"? For example, the Python Docs say itertools.chain(*iterables) ... Equivalent to: def ...
7
votes
1answer
186 views

How to document a Ubiquitous Language?

Our company is in the process of converting a lot of manual business processes (and the associated institutional knowledge) into new enterprise software. The project is going really well, but as we ...
1
vote
2answers
106 views

Use a hash character or a dot when referring to methods and fields in software documentation? [closed]

Assuming I have this class (Java code only for the sake of example): class Person { private String name; public void setName(String name) { this.name = name; } } When I write ...
0
votes
1answer
101 views

Docstring convention for Python __str__, __unicode__, and __repr__ class methods

What is the docstring convention in Python for the following "magic" class methods: __str__ __unicode__ __repr__ Should I add docstrings for these? If yes, what should they say (for each)?
1
vote
1answer
82 views

How to document GUI screens transitions of a complex application

There is an application based on multiple screen model with pretty complex net of transitions between these screens. It has some similarities to a web page or Football Manager like games. Its main ...
1
vote
3answers
173 views

Should I use future or present tense when writing a design spec document?

I'm writing a Design Specification Document for a college project and wondering about the tense I should use. The development on the project has not yet started, I'm just writing the UI design ...
0
votes
0answers
22 views

Organising client-server projects

I am about to spin up a new development in my shop. It will be our first client-server application. It will be written for .NET 4.6 using C# and visual studio. WCF will be used for interprocess ...
2
votes
1answer
158 views

How do I represent a schema diagram of my MongoDB database?

I have a MongoDB database that I want to properly document its schema design. I know that MongoDB is a NoSQL database and is schemaless by nature, but I do enforce a schema through my application and ...
1
vote
0answers
47 views

Is there a good way to create an FAQ section within a markdown README.md [closed]

I have a small project where I want to put the FAQ into the main README.md page without having to fuss with manual formatting of it and ideally with collapsing sections to make it easy to scan the ...
0
votes
1answer
81 views

Should I document expected call-sequences when call-order matters?

In dynamically and weakly-typed languages*, I often find myself with structures like the following pseudocode: class Stateful: # [ various datamembers / attributes / properties / fields / etc. ] ...
1
vote
1answer
93 views

PHPDoc Comment, Class vs File

I am trying to standardise my code as much as possible, including DocComments, using PHPCS. It seems that the PEAR standards contain two sniffs that require almost exactly the same tags appear in the ...
2
votes
1answer
91 views

How to generate learning material from your work [closed]

Catalyst: Recently my team has been tasked with bringing in house a large software project that has been worked on for over 20 years. Some of the old development team is still around, and originally ...
2
votes
0answers
55 views

Standard for order of tags in PHP DocBlocks?

Based on the tags listed from this "standard", is there an order of the tags that people typically follow? Even if it's not something that has been entirely accepted, but something proposed? I am ...
5
votes
5answers
628 views

Debug function input vs expecting code users to read the documentation - How far do I go? [duplicate]

I could write an endless amount of debugging code to handle the various components of input for a function, check that the correct data types are used, make sure things are decendants of the proper ...
1
vote
4answers
117 views

How to keep documentation up to date and accessible [duplicate]

The problem: Documentation is in code in the form of docs, its in wiki websites, its written down on notes, in diagrams and issue management systems. When documentation is so spread out, how does ...
10
votes
4answers
1k views

Why should comments / documentation of a JavaScript function include so much? [duplicate]

I was researching proper commenting practices for JavaScript and highly upvoted answer (+100) cites JSDoc-like commenting. JSDoc promotes comments like this: /** * Represents a book. * @constructor ...
8
votes
5answers
319 views

How to prevent changes to an internal API from breaking other projects?

We have like 20 - 30 independent modules/solutions. Each of these has about 7 - 10 projects with different classes, components, etc. These are all used internal to our company. Our problem is when ...
1
vote
2answers
177 views

When is documentation, unit testing, QA and refactoring meant to be done in a 2 week agile sprint?

The team I am working on is trying to do agile development with 2 week sprints. I think we must be doing something wrong however, as we have to work like madmen to get the features implemented in the ...
3
votes
1answer
72 views

Methodology for exploring APIs in dynamic languages

As a regular user of Standard ML and, to a lesser extent, Haskell, the following pattern is deeply ingrained into my "instinctive" approach to navigating and learning new APIs: Understand the types. ...
22
votes
6answers
3k 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
165 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 ...
95
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 ...
6
votes
2answers
256 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
40 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
94 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
52 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 ...
5
votes
3answers
108 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: ...
0
votes
0answers
111 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 ...
5
votes
4answers
177 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 ...
1
vote
1answer
97 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
2answers
228 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
204 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 ...
0
votes
3answers
3k 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 ...
3
votes
1answer
753 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
190 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 ...
4
votes
1answer
114 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 ...
3
votes
3answers
291 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 ...
3
votes
1answer
516 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 ...
1
vote
0answers
156 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: ...
-2
votes
3answers
150 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 ...
5
votes
2answers
2k 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 ...
1
vote
1answer
107 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 ...
6
votes
2answers
135 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 ...
0
votes
3answers
91 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() { ...
2
votes
2answers
99 views

Include internal defects into the release notes?

When delivering a product, Release notes clearly contain known issues found by customer in the previous build. But should we include defects that we, as a supplier, found during our testing, those ...
3
votes
3answers
185 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 ...