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

Questions tagged [documentation]

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.

-2
votes
0answers
18 views

Why does Eclipse generate two javadocs for module-info? [on hold]

When creating a new module in a java project in Eclipse using Java SE 10, Eclipse autogenerates amodule-info.java file. Here's the format it provides: /** * */ /** * @author [my name] * */ ...
-5
votes
0answers
52 views

Should businesses invest money in documenting product knowledge and system architecture? [on hold]

When product or system documentation is poor, is this typically a conscious business choice by companies? Is documentation usually not as valuable to organizations as hiring more developers to ...
2
votes
2answers
60 views

How thoroughly should you document business flows for a product or system you are learning?

I work on applications that have user documentation but it is not organized or updated to the current release. Is it worth my time to create my own documentation with screenshots and notes on all the ...
1
vote
1answer
101 views

Are formal Product Specifications still relevant? [closed]

I had a conversation with a recruiter recently. As a contract engineer, I've worked several jobs over the years and it's been ages since I saw a formal specification. Confluence pages, yes. Jira ...
0
votes
1answer
50 views

Firmware Design Document (FDD) for an embedded system

What is a firmware design document (FDD) in terms of an embedded system? I am working on developing an application that would be working on a customised board similar to the Xilinx Zynq Development ...
4
votes
1answer
146 views

How to document multithreaded applications

I'm working as a support engineer, having access to the source code, and I'd like to use this opportunity to document the source code, but I stumble on a first question: how do I even start? For ...
-2
votes
1answer
148 views

Should a developer write “Solution document” before start coding?

Why we do this is for "Planning before we code" and one another point is to "help the newcomers in the team". We are a team of 5-8 members. We do have API documentation and Readme included with our ...
-1
votes
2answers
70 views

How should docstrings be used in modules with one class?

When authoring OOP code, sometimes you have a file that only contains one class, and nothing else. PEP8 says that all modules and all classes should have docstrings outlining what they do. But in ...
-2
votes
1answer
70 views

A fully working webapp without architecture or complete documentation what to do

We have a webapp (ecommerce webapp) where we are currently working on. For some functions we wrote UML diagrams and ERD diagrams. We just made a high level architecture of the website. But the ...
1
vote
1answer
67 views

Are file summary comments a good way of knowing what each file does?

I want to know if including a file summary comment at the beginning of each file is a good way of knowing what each file does or is there a better way.
-1
votes
2answers
221 views

How to keep track of all functionality in a large application

As the title says - how to keep track of functionality as the application grows large? My company use Word-documents where the application has been broken down into chunks called "use cases" - which ...
108
votes
4answers
13k 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
39 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
66 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
501 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
92 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
4k 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
74 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
303 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
50 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
364 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
1answer
321 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, **...
22
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
415 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
72 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
312 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
381 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
243 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
347 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
93 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
233 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
125 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
76 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
164 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
120 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
278 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
292 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 ...
1
vote
2answers
549 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 ...
6
votes
2answers
3k 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
150 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
55 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
519 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
355 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
140 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
195 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
2k 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
367 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, ...
5
votes
4answers
1k 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 ...
6
votes
4answers
455 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
2k 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 ...