Stack Exchange Network

Stack Exchange network consists of 174 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Visit Stack Exchange
Join us in building a kind, collaborative learning community via our updated Code of Conduct.

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.

107
votes
3answers
12k views

What's the phone number equivalent of example.org?

RFC 2606 standard reserves the domain names example.org, example.net and example.com for the purpose of being used as examples in documentation. What is an equivalent for a phone number (including ...
0
votes
0answers
34 views

Are REST Resources and GraphQL Object Types conceptually equal?

I'm in the process of outlining the intended business logic of a web service. At this point, I'm not too concerned with implementation details. On the contrary, I'm looking for ways to abstract them ...
3
votes
1answer
58 views

Where should I specify validation messages?

I'm creating a Functional Specification Document (FSD) for a project. I'm pretty confused as to where I should specify error messages? Do they belong in the FSD, or are they part of the Technical ...
2
votes
2answers
165 views

Technical documentation vs Software design documentation

I am trying to start a documentation about a class library that is already finished/developed. The purpose of the documentation is to be used by other developers in order to understand what kind of ...
2
votes
2answers
78 views

Communicating the intended operation of API business logic to both developers and business people

Currently, I'm designing the intended operation of a (RESTful) API which a team of developers will eventually build. I'm not concerned with implementation details, as long as inputs are correctly ...
11
votes
6answers
3k views

Can creating a Software Design Document after development be justified?

I'm currently working on my graduation for my "Software Development" studies, in which I have to develop complex software individually in an external company. This all needs to be done in a structured ...
0
votes
0answers
73 views

When documenting code, should you seperate different languages into different documentations / files?

I am currently working on a project with hundreds of methods, I started it blind without any documentation and im only now starting to put in documentation. I have 2 major languages within the code, ...
-2
votes
1answer
300 views

What technical documentation to share and not to share to a wide public?

I work as a backend developer in a financial organisation and the organisation has demanded that we migrate all our technical documentation (e.g. info about batches like the names and their scheduling ...
0
votes
0answers
47 views

How-to incrementally improve JavaDocs

I started working at a new company in the past year. I'm used to having pretty complete JavaDocs with edge cases noted (such as what happens when null is passed to the method). I'm pushing for making ...
2
votes
2answers
331 views

How much information should a docstring contain

I have function that takes as arguments a number of classes of average complexity. When writing docstring for that function, I'm running into a series of questions: Should I describe (besides what ...
0
votes
0answers
77 views

How to document kwargs in Sphinx style?

I'm wondering how I can document **kwargs in Python using sphinx dostring style. For example I have the following method and I want to document more details about kwargs. def get(self, url=None, **...
21
votes
6answers
6k views

How do I document my code for minimum time review? [closed]

I want to document my code such that there is minimum need for reading and browsing the code again months later. I know that there are different types of documentation (in source code and outside, ...
-1
votes
1answer
166 views

Who writes a functional specification in a software company? [closed]

Who writes functional specification in a software company ? Given a software company typically comprises of Software Engineers, Engineering Managers, Product managers and Directors?
1
vote
2answers
69 views

what tool or methodology to use to do impact analisys in a distributed system?

We are working on a large (legacy) distributed system with various applications, messaging (soap services, database dblinks, rest services)... We are lacking for documentation and a big view of this ...
7
votes
2answers
238 views

Maintaining and documenting API endpoints of many applications in a microservice architecture

I think one of the biggest pain points in working with microservices is making sure that the APIs are well-documented and APIs do not change their behavior without affecting downstream applications. ...
1
vote
1answer
130 views

Understanding use case levels

I've found out that there are 5 use case levels: Level 0 Cloud Level 1 Kite Level 2 Sea Level 3 Fish Level 4 Clam Cloud level lists only high level users goals such as "Manage files". Kite level ...
4
votes
4answers
232 views

Do I need requirement analysis if there's no client?

I think it happened to everyone, having side projects, trying to do something new and big in their spare time, or maybe having a little startup where everyone has clear in their mind what the software ...
3
votes
2answers
325 views

how to document the results of programming for non-programmers

I keep running into a problem at work, and I'm hoping that others know a solution either from personal experience or from best practices. I am not a programmer. I do, however, heavily use RDBMS ...
2
votes
2answers
77 views

Make sense out of automatic information gathered from legacy system

I have a legacy system I need to plan a migration for. It's mainly developed in Ingres+4GL (an old Ingres based form system). I have the following information: Data Structures (data base relations ...
1
vote
3answers
218 views

how to write good software design documentation for an old project with limited documentation?

Two months ago I joined a development team for implementing new features over a software that evolved over 10 years. The current state is that there is very few documentation and in order to develop a ...
-3
votes
2answers
123 views

What is a standard procedure while parallelising a serial code [closed]

I have a C++ serial code which simulates a physics algorithm. The C++ code is serially optimised. What is the standard procedure and documentation that is followed while parallelising the code or for ...
-4
votes
1answer
75 views

What non-essential files should be included in end-user package?

I'm working on a free software GUI application and we are considering what non-essential files to include in the end-user package Here are my thoughts of possible files we may want to include: ...
1
vote
3answers
157 views

Documenting a new feature

I have recently started working on a complex project and recently had a team meeting where a new feature was discussed. I am not happy with the current architecture, because the system is undocumented....
2
votes
1answer
116 views

When and why during software reengineering sometimes the document reconstructing is skipped?

While studying the book of Software Engineering by author Roger Pressman I came across this point about software reengineering , where it is written in the book that if creating documentation is time ...
2
votes
1answer
148 views

What is the difference between a man page and --help for a Python script?

I'm currently developing some Standard Operation Procedures for the company I work for. I'm starting with the very small examples; like scripts. There are currently several scripts being written in ...
3
votes
3answers
284 views

Is there a well known way to document the process done before writting any code?

What I Want to do I'm in a process of sketching, prototyping and brainstorming to know the possibilities the code will deal with and what kind of problems I could face while writing the code. And ...
0
votes
2answers
435 views

How to approach the understanding, documentation and validation of legacy code [duplicate]

I've been tasked with studying a Python code, which runs on an orchestrator, which schedule the launch of the code in correspondence of some events. The code imports some modules, and it's basically ...
5
votes
2answers
2k views

What to include in “technical documentation”

I have the task to write the "technical documentation" for a software which I was developing. One reason or another I have never done this before, I do have experience with SRS, but this is something ...
2
votes
1answer
114 views

Describing JS program flow in @fileoverview

I have to edit other people's JavaScript code. The code usually loads some data from a Web API, generates a table, places it into the HTML page, and attaches some event handlers. Due to the async ...
0
votes
1answer
54 views

Should usage examples in XML documentation be explicitly tested?

If usage examples are provided in XML documentation, should those examples be explicitly tested? /// <summary> /// Gets a collection of Foo objects. /// </summary> /// <param name="...
0
votes
1answer
194 views

How should I handle docstrings of subclass methods?

I have an abstract class structured somewhat like this: class AbstractQuery(object, zip_code): def execute(self): """ Retrieve information about a zip code The information ...
10
votes
4answers
354 views

Include a link to relevant documentation in error message?

We create a commercial library and code examples that are being used by external developers. We have (closed, available to registered users) documentation that extensively explains how to use the ...
4
votes
2answers
138 views

README “Setup” section best practice?

In the SETUP section of my README, should I just link to instructions for each dependency like this: STEPS install Appium (guide) install XYZ (guide) Or should I reproduce all their instructions ...
3
votes
2answers
169 views

Should I show the association class in my class diagram?

For example I have a relationship like this: user (0..*) buys product (0..*) Which results in an association class, called sale, which has the userID and productID. Just for the question's sake, ...
4
votes
3answers
1k views

UML Class Diagram: How to describe method functionality?

Recently, we have learned about UML class diagrams in university and I began applying that knowledge to my work projects. However, I am still unsure how or where I am supposed to describe the ...
-2
votes
1answer
301 views

Software documentation steps

I am trying to write documentation for a project and I have trouble finding information about list of documents that need to be written. I know there are Vision and Scope, User Requirements, ...
4
votes
4answers
867 views

Is it consider bad practice to formally document implementation code?

PEP-8 clearly states which parts of your code should have documentation: Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public ...
4
votes
4answers
378 views

What is the antonym to “legacy code”? [closed]

I am writing a software documentation and I need a antonym to "legacy code". Is there any established word for the antonym to "legacy code"? I'll need this antonym to describe that code which was ...
10
votes
4answers
1k views

Is there a standard for documenting a program's high-level architecture?

I am an amateur developer and all my programs up to now were simple enough to be documented within the code. While reading the code it was clear what I was doing such and such action (my standard test ...
7
votes
4answers
2k views

Best practice to mark a method that is called via reflection?

Our software has several classes that should be dynamically found via reflection. The classes all have a constructor with a specific signature via which the reflection code instantiates objects. ...
1
vote
1answer
56 views

Should I doxygenate implementation files in a library of mine, in addition to the headers?

I'm in the process of writing Doxygen comments for this library of mine; it's a header-mostly C++ library, but it does have some code which gets linked rather than included. For that code, which has ....
7
votes
2answers
146 views

Keep documentation version the same as project version

In addition to this question Should Git be used for documentation and project management? Should the code be in a separate repository? I want to ask if it is recommended to keep the documentation ...
2
votes
2answers
127 views

Is there a standard way to refer to items inside a menu when writing documentation?

At several times in the past while writing software documentation -- including user manuals, user stories, bug reports, test cases, and emails to users/colleagues -- I've needed to be able to refer to ...
3
votes
0answers
766 views

Representing a user event in a flow chart

I was wondering which symbol should be used for representing a user event (i.e. button click). seems like it should suffice, but isn't a user click technically ?
3
votes
1answer
104 views

How to document logical proofs against race conditions?

Specific Background I'm writing a library to extend the async backbone of a language with cooperative multitasking. (The language is Hack, but C# also implements async-await with Task, if the concept ...
0
votes
1answer
252 views

Technical Design document and external agency

My company is recruiting an external agency to do a site redesign/development (agency has not been selected yet). Regarding the technical design document, should my company produce that document or ...
4
votes
2answers
1k views

How to document REST API before coding

My team is working on a web application using Micro Service Architecture and Angular + Spring MVC. We follow Agile development. For each story, we create few implementation and test tasks. Documenting ...
0
votes
3answers
163 views

What is the need for a cookbook as opposed to having just a reference manual? [closed]

What suggestions would you make to write a cookbook to use a distributed database? Does having a tangible end goal enough to distinguish a cookbook from a reference document? What else should I ...
1
vote
0answers
54 views

Adding documentation after modifying the code

In our TFS (Version 14.102.25423.0) I can click Browse on home page, then under Browse Server, pick my project and hit Navigate. Once inside my project, I see tabs like Home Code Work Build ...
4
votes
3answers
2k views

Release notes for first version

I understand what to include in ordinary release notes - there are many questions and answers relating to that. What should I include in the first set of release notes, i.e. for the very first ...