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

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
31 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
22 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 ...
5
votes
2answers
165 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) ...
1
vote
4answers
267 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
183 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
3k 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
55 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
80 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
156 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
65 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
388 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
24 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
116 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
81 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 ...
7
votes
5answers
12k 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
60 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
30k 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
78 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
156 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)?
7
votes
1answer
264 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
150 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
479 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
179 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
568 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
424 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
31 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
148 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
66 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
376 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 ...
1
vote
1answer
218 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 ...
8
votes
5answers
360 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 ...
2
votes
1answer
96 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 ...
5
votes
5answers
646 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 ...