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
-2
votes
0answers
29 views

How to document complex software projects? [closed]

I want to learn how to document complex libraries or software products. My goal is that the clients, the requirement team and the developers understand what the product does. I want this document to ...
1
vote
2answers
114 views

How to structure the project documentation?

I just started our bachelor thesis, and want to ask you how to make a proper documentation. There are two pieces of software in our project's scope: a microcontroller software (node), and a server ...
9
votes
2answers
327 views

How should I make it less scary for a team to create diagrams?

Context I am a strong proponent of clear, illustrative diagrams in documentation. When they are properly done, they improve a lot two aspects: the understanding of the documentation and the time a ...
-2
votes
2answers
84 views

How to document pitfalls and gotchas in the code base?

What are some ways of documenting pitfalls and gotchas when working with a codebase with a team of developers? I'm working with a team of developers on a big codebase and there's lots of small little ...
2
votes
4answers
221 views

How to deliver fast and avoid growth challenges with a codebase?

Startup Context A friend of mine recently asked me to be a part time software engineer for her startup which has yet to write any code. She is fairly serious and has already raised a fair bit of ...
4
votes
2answers
135 views

Testable documentation

I'm creating a library, and I would like to provide a tutorial on how to use the library. Such a tutorial will contain code snippets as usage examples; therefore, I would like to test these snippets ...
4
votes
2answers
263 views

How to maintain a project documentation?

How is it done in practice to maintain a project documentation but not the documentation to the users but the doc for the maintainers. For example, is it customary to just look at the files and ...
1
vote
2answers
163 views

How to write software requirements for an existing product

Over several years, a company developed a multi-disciplinary (firmware, software, hardware) product. No SRS (Software Requirements Specification) was ever written. A prospective customer now wants a ...
5
votes
2answers
224 views

How to keep parser code and grammar definition in sync?

I am working with a custom, fairly simple DSL for specifying how various scripts will be run. The DSL takes the form of config files that are very simple and easy for humans to read. They define what ...
2
votes
1answer
56 views

Describing Data Fields in Business Requirements Document

How and where to describe data fields and their behavior in business requirements document? I have business requirements document setup this way: 1.4 General Requirements: Req # | Ranking ...
2
votes
3answers
192 views

Software Quality - preventing regressions with documentation

I lead a small but growing team of developers on an iOS application with a server backend. We have comprehensive unit and integration tests on both ends. As the product grows, I want the onus of "...
6
votes
5answers
379 views

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

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
162 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
81 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
77 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
200 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
36 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
101 views

How to keep track of db tables used in various apps [closed]

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
172 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
9k 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 ...
3
votes
1answer
376 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
76 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
123 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)...
3
votes
2answers
324 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
38 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 ...
4
votes
2answers
155 views

How to convert a use case to a use case diagram?

Suppose I have a use case, like this example. Normal Flow: The user will indicate that she wants to order the items that have already been selected. The system will present the billing and shipping ...
1
vote
2answers
203 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
119 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
187 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
112 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
119 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 ...
1
vote
1answer
1k 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 ...
7
votes
1answer
359 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
169 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
234 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
75 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
77 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
315 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 ...
115
votes
3answers
15k 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
76 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
2k 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
177 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
308 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
539 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
1k 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
996 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
74 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
521 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 2 3 4 5 12