Questions tagged [documentation]

Software documentation is written text that accompanies computer software. It explains how the software operates, how to install it, how to use it, and other resources for help.

Filter by
Sorted by
Tagged with
6
votes
5answers
339 views

Tips for doing “emergency documentation” of complex embedded project before leaving?

I am looking for advice for doing "emergency documentation" for a large and complex software module in the technical/embedded domain, that I worked on for several years. I am going to leave the ...
2
votes
2answers
142 views

Documenting Dependency Injection Parameters

Should documentation be added for constructor parameters that are passed via dependency injection? In my current project I have decided to omit documentation to describe each of these parameters and ...
0
votes
1answer
70 views

Is there an advantage of generating/hosting documentation?

I always document my Python code with numpydoc style docstrings. For my private projects, I also generate the documentation as HTML and host them. That is super helpful because this way I can Google ...
1
vote
1answer
76 views

What is the word for the “shape” of json requests/responses? [closed]

For example, what would you name a module containing all of the Pydantic models for your FastAPI project? What would you put as a subtitle in your documentation below an example JSON api response? In ...
-2
votes
1answer
152 views

What is the meaning of 'code vetting' in Software Engineering? [closed]

I saw the term code vetting for the first time in a gerrit review page. What does it mean? The line I came across: "No XYZ check was done. However, if this project is intended to be shipped in ...
0
votes
0answers
35 views

Classification of methods that are only accessible by a child class and its parent

I'm trying to document some of my JavaScript according to this JavaScript Documentation guide and came across member access (private, public, protected). I was wondering what the classification would ...
1
vote
2answers
93 views

How to keep track of db tables used in various apps

I have N applications using ORM, SQL-statements and stored procedures to access M tables from an MSSQL Server 2017. There are some shared tables that are used by various apps. Let's say I am forced to ...
2
votes
1answer
104 views

Is it okay to use a patch version in semver when updating documentation?

How does one go about e.g. missing documentation in the source files when using semver? I have just released 1.0 of my library and noticed that a class is missing JavaDoc - is it ok to release a PATCH ...
49
votes
8answers
8k views

Should generated documentation be stored in a Git repository?

When you use tools like jsdocs, it generates static HTML files and its styles in your codebase based on the comments in your code. Should these files be checked into the Git repository or should they ...
2
votes
1answer
158 views

Suggestions for documenting namespaces with Doxygen

Consider several C++ classes which are all defined in a particular namespace. For cleanliness, each class is located within its own file, and are each well-documented. For the purposes of completing ...
-1
votes
1answer
60 views

Documenting a distributed application [closed]

Recently, I've became the integration lead for a large distributed system. I have two main challenges before I can take on anything else: first document all system interfaces and it's relationships ...
1
vote
2answers
121 views

Multiple use/semantics of the same database fields - is it acceptable practice?

I have ERP database whose good or person entities each have several hundreds of fields. Many of them are used for some subjects only. And hence senior companions (especially from the business division)...
2
votes
1answer
113 views

Sharing Docstrings between similar functions?

Assuming we have different classes with methods that possess the exact same description, however execute code a bit differently for the same return type. class Foo: """This is the Foo class ...
-1
votes
1answer
37 views

How to write documentation about field correlations?

Currently we are integrating with a 3rd party system. This includes data sent to this 3rd party where the customer is able to see it. My current task is to provide visual documentation (PDF) about ...
1
vote
2answers
201 views

How to find already existing code | How to arrange code in a way it can be found again [closed]

I'm refactoring the framework of our company, trying to fix the issues we had in the past. We're a team of 6 developers, and we have various needs and issues in regards to tidying up our framework. ...
0
votes
1answer
85 views

How to document changes to a project

A company I work with uses a "skeleton" project as base scaffolding for each project they have. I work on several edits to the skeleton. Some of them are few lines on huge source files. What's a good ...
3
votes
1answer
90 views

How to structure SW documentation with SOUP components

I need to produce some documentation to be compliant with IEC 62304 and, while reading all of the processes needed to be documented, I'm having a couple doubts about how to structure the whole lot of ...
3
votes
2answers
100 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
115 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
655 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 ...
5
votes
1answer
267 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
155 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
155 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
74 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
74 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
vote
2answers
291 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 ...
112
votes
4answers
14k 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 ...
4
votes
1answer
75 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 ...
4
votes
2answers
1k 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
147 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 ...
-2
votes
1answer
307 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 ...
2
votes
2answers
476 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 ...
1
vote
1answer
961 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
846 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
73 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 ...
8
votes
2answers
460 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
851 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
270 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 ...
4
votes
2answers
369 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
117 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
391 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
129 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 ...
-1
votes
1answer
87 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
205 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
128 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 ...
3
votes
1answer
471 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
300 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
810 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 ...