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
0answers
38 views

Tips on reading undocumented code? [duplicate]

This summer I got my first position as a programmer (intern), but it has been a disaster. Before the internship they misled me; they didn't tell me they were developing Django apps and told me to just ...
15
votes
7answers
8k views

Are wikis really appropriate to store documents for software development? [closed]

Everybody knows that well-documented software development leads to success. However, it usually means that not only plain text but also binary content will be involved in the document, such as a UML ...
2
votes
1answer
47 views

Documentation for unit tests

I have a small project written primarily in C++ which is documented with Doxygen and tested with a unit testing framework (Google Test in my case, but that doesn't matter). I wrote several test cases ...
12
votes
2answers
76k 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?
5
votes
2answers
168 views

Set of specific values implementation vs. using some sort of generic set with advanced checks

I am working on a set implementation in JavaScript currently. This should kind of simulate generics as known from Java or C#. I need a mutable version of that (allows for adding/removing set values) ...
4
votes
5answers
6k views

How to properly document functionality in an agile project?

So recently, we've just finished the first phase of our project. We used agile with fortnightly sprints. And whilst the application turned out well, we're now turning our eyes on some of the ...
3
votes
2answers
152 views

Should I document overloaded operators in C#?

So I have been working on a C# Matrix library. I've been documenting it really good so far. The thing is I don't know if I should document my overloaded operators, I mean, it is kind of obvious, isn'...
23
votes
7answers
3k views

Release first or document first?

I've been working on a project for a couple years now, and I'm starting to gather a decent user base. I've created a project page with some basic documentation, but it's really not much more than a ...
0
votes
0answers
32 views

Formal documentation - frequent Support-Cases

I have the task to document support cases for some Interfaces, which happen on a frequent base. This documentation is for the stakeholders: Developers for a new Interface Domain Exports Technical ...
1
vote
0answers
27 views

Shared pointers across threads in UML for class and sequence diagrams

How does one represent shared pointers across threads in UML for class diagrams and sequence diagrams? I especially want to document the ownership of the memory even though it's accessibility (a ...
1
vote
4answers
274 views

How to mark/track features in code?

After some time in every project sooner or later you will need to find a feature in it a fix it or extend it so I was wondering if there is already a system or a convention for marking those features ...
7
votes
3answers
188 views

Is it bad practice to add external links in documentation?

Often I find myself solving bugs by finding the answer on Stack Overflow. Is it bad practice to add a snippet of why I did what I did and then add a link to an article or page from the web?
9
votes
5answers
4k views

How to document business rules

I am wondering what would be the formal and the most commonly practiced method of documenting business rules? Also how do you document the UI specifications of development artifacts (e.g. Documenting ...
1
vote
1answer
61 views

Dividing software into requirement layers

In order to be able to create better documentation, better tests and to start using the just gotten to know requirement traceblity matrix I'm trying to understand the different software requirement ...
1
vote
2answers
83 views

Implementing something partially vs providing simple documentation?

I often encounter the following program while programming. There is a "partial" solution to a problem, which provides all the functionality that is necessary, but the documentation explaining said ...
5
votes
2answers
157 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... ...
1
vote
0answers
40 views

Should I use RFC 2119 in interface documentation?

RFC 2119 defines several terms, including MUST, SHOULD, and MAY, for use in standards documents, particularly those relating to networking protocols such as IP and HTTP. These terms are widely used ...
0
votes
2answers
80 views

is there a standard for documenting requirements interview

We're university students taking a course in information systems engineering. We have project and we've had a meeting with the teacher playing the role of a dentist and a helping girl playing the ...
1
vote
2answers
406 views

Questions to ask a 3rd party API provider [closed]

I'm due to meet with a developer/sales person from a new 3rd party resource we're about to start using. The main topic I'll be interested in, is their API as I will be the developer making use of it ...
0
votes
0answers
26 views

Requirement/analysis documents in branch-per-branch versioning enviroment

Our ALM is implemented in TFS where for every team project we employ branch-per-feature approach. Each feature may contain multiple backlog items. For each team project we need to maintain master ...
-2
votes
2answers
138 views

Where can I find software project deliverables/ documents to help me professionally document my projects? [closed]

Hie guys. I have never been employed in the software development industry and when I do projects I usually just draw non-standard diagrams or used use case diagrams and class diagrams. This time a ...
2
votes
1answer
82 views

Does license have to be in text format?

Does a software license have to be in text format? I am thinking of adopting the MIT license to my software. I have a documentation in HTML format, which is distributed together with the software, and ...
1
vote
2answers
1k views

How do I read API documentation? [closed]

I've been trying to read through the RoR API to try to learn things that the tutorial missed, and I haven't been able to follow it at all. The only time I've read documentation was when I needed to ...
1
vote
1answer
47 views

How to avoid repetition in docstrings?

I find that in my code, many methods in a class or a set of related classes have quite similar arguments: Arguments: dt_start (datetime): Starting date. Needs to meet complex requirements x and y ...
8
votes
5answers
13k views

Creating a coding standards document

I work in a control systems company, where the primary work is SCADA and PLC, along with other control systems stuff. Software development is not really something the company does, apart from little ...
0
votes
2answers
61 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 ...
5
votes
4answers
6k 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 ...
8
votes
4answers
31k views

What is an “implementation plan”? [closed]

I was recently given the task of creating an implementation plan document. When I asked for an example of one that I could look at, I was told to look at the Project Plan that had already been created ...
5
votes
1answer
87 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 ...
23
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 chain(*iterables):...
0
votes
5answers
1k views

Named output parameters vs return values

Which code is better: // C++ void handle_message(...some input parameters..., bool& wasHandled) void set_some_value(int newValue, int* oldValue = nullptr) // C# void handle_message(...some ...
1
vote
7answers
1k views

Should you use “internal abbreviations” in code comments? [closed]

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 ...
0
votes
1answer
169 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)?
8
votes
1answer
299 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 ...
69
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 ...
1
vote
2answers
172 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 ...
4
votes
6answers
483 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 ...
0
votes
3answers
2k views

Is there a difference between property and attribute?

These two words are completely synonymous for me, but I wonder if there's actually a useful semantic difference that I can incorporate into coding/naming conventions/process.
17
votes
2answers
8k views

What standard superseded 830-1998?

I have been looking into how to document software projects more formally, and I have learned about IEEE 830-1998: Recommended Practice for Software Requirements Specifications. However, as you can ...
18
votes
5answers
5k views

What grammatical tense should I write my specifications in?

We are currently writing functional and technical specifications in a two column format; summary sentence and technical detail. The details often refer to an appendix with diagrams, layout designs ect....
68
votes
17answers
14k 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 ...
1
vote
1answer
204 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 ...
3
votes
1answer
687 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 ...
7
votes
6answers
1k views

How useful are function points? [closed]

How useful is it to measure function points? We use function points at my new job. I've heard of function points but haven't had any training or experience... but I don't have much confidence in ...
1
vote
3answers
498 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 section....
0
votes
0answers
33 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
2answers
184 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 ...
1
vote
0answers
79 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
90 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. ] ...
6
votes
6answers
380 views

Hyperlinked, externalized source code documentation [closed]

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 ...