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
-4
votes
0answers
30 views

ABAP SAP documentation tools

I was wondering if there was an easy way of documenting abap developments via a tool (documentation generator) or framework? Like for instance if you have a transport request. To like generate some ...
12
votes
4answers
866 views

What is the meaning of the quote: “A bug in the code is worth two in the documentation.”?

As I boot up Eclipse for C++ with the "Darkest Dark Theme with DevStyle" installed, it spits out quotes--one per day. Yesterday's was: A bug in the code is worth two in the documentation. ...
2
votes
1answer
50 views

AMQP messaging: How to document for consumers

My application publishes various messages (e.g., telemetry, changed-events, ...) to a RabbitMQ message-broker. The users have no access to the source-code and therefore, will need a separate ...
0
votes
2answers
177 views

Errors that don't make code behave wrong from user's point of view - how would you call them?

var file_extension = 'txt'; if (file_extension === 'txt') alert('plain text'); else if (file_extension === 'md') alert('markdown'); var file_extension = 'txt'; if (file_extension === 'txt') ...
-1
votes
1answer
71 views

How should I document a higher-order Python function?

I'm interested in designing a high level function in Python, (I.E. a function that takes other functions as arguments) but I don't know of any good conventions for documenting such a function. For ...
4
votes
3answers
258 views

How to visualize a Stream object (and some other data types)?

I want to make a small programming tutorial which will have a number of images visualizing various data types, but I am not sure how to draw these images of the data types. Assume that I have a ...
-4
votes
3answers
96 views

Documenting a project in a README.md and in a Wiki page?

I work on both frontend and backend applications and I still wonder how to document those applications. When we start a development, we usually : Start a README.md that describes the application ...
1
vote
2answers
58 views

How to write documentation for CLI app that requires stdin?

I am writing CLI program that can accept very long strings. For this reason I decided to pipe the data into the program as I would hit limitation of the shell / OS. How should these CLI program ...
16
votes
3answers
2k views

When to add version numbers to documentation

It is often useful to document when (i.e. in which versions) a feature was added, marked as deprecated, etc. For example: Function FooBar(x, y, z) Foos x with y and bars them with z. (Parameter z was ...
-3
votes
1answer
80 views

In Java API documentation, what does it mean to inherit an abstract method? [closed]

Here's an example: In the documentation for java.util.HashSet, there's a list of "Methods inherited from interface java.util.Set", including equals, which is an abstract method in java.util....
-5
votes
1answer
77 views

Giving a fixed project price when REST is involved

Whenever I am asked to give a quote for a project that involves a remote REST API, I become very cautious. Most of the REST API's I worked with had a documentation, but it usually turned out to be ...
34
votes
8answers
10k views

Literate programming vs reasonably documenting your code

In a project that aspires from the onset to be maintainable across a revolving team of developers, what difference would it make to use literate programming against thorough commenting guidelines? The ...
-3
votes
1answer
144 views

Does the intrinsics functions from Intel Instrinsics Guide also works on AMD CPUs?

The link bellow is the Intel Instrinsics Guide for intrinsics functions. (SSE, AVX, etc.) https://software.intel.com/sites/landingpage/IntrinsicsGuide/# Does this functions also works on a AMD CPU, ...
4
votes
4answers
214 views

How to describe a function argument that is used as a hint/best-effort?

Say I have a server exposing an api that let me retrieve 'things', there are a lot of things, and as such retrieving all things at once could take down the server, hence the exposed API returns ...
0
votes
2answers
50 views

Do we draw the dataset as a secondary actor in a use case diagram?

I am working on a project to detect cancer and I am using deep learning (Convolutional neural network). In the user interface, the user has only to input an image number then click test when the user ...
-2
votes
2answers
109 views

Architecture of new software documentation

My question is related to designing new software. Let's say I work in a medium-sized company that has a core product. Now we want to start with new software (purpose of the application is different ...
2
votes
4answers
115 views

How do I write, review and coach better English language in documentation?

My job regularly involves writing and reviewing (in the form of pull requests) English prose in the documentation for our internal system, which solely faces other developers, in a strongly American ...
1
vote
1answer
56 views

How to improve readability of a specification document containing lots of tables?

We maintain a technical project whose specifications are in a document of few hundred pages. It's a text document (Word), not a Wiki or a Web-based stuff. The document contains lots of tables with ...
2
votes
1answer
139 views

In what file do I put the installation steps in my git repository?

I have a git repository and I would like to add the installation steps required to make the project work locally. The project is a company and private project and users will also be contributors. I'm ...
1
vote
2answers
207 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
339 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
96 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
236 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
170 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
272 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
289 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
228 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
204 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
202 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
383 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
192 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
86 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
80 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
317 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
37 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
112 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 ...
3
votes
1answer
312 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 ...
53
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
607 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
144 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
125 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)...
4
votes
2answers
850 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
39 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
228 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
170 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
368 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
120 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
2k 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 ...

1
2 3 4 5
12