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
-5
votes
1answer
35 views

Distinguish between User Guide and README.Md [closed]

I am tasked to create a readme file but I am not sure what I should include details on how to use the app.
-2
votes
1answer
36 views

What is the proper diagram to describe an event subscriber final graph?

I'm working on a microservice application and I need to describe the complete execution graph of a specific event being published, where each node in the graph is a specific microservice subscription ...
-1
votes
1answer
48 views

Writing Release Notes for gradual feature rollout

Our software product is not complete, but it is functional enough that one of our clients is using it. We produce release notes with every sprint. The notes are divided into sections such as "New ...
1
vote
1answer
133 views

How can I write good Conventional Commit-style commit messages for one feature over multiple commits?

If I am working on a single feature, I would usually commit multiple commits. Should every commit start with feat? Or should only 1 commit have the type of feat and use a different type for the other ...
41
votes
7answers
10k views

Should a rookie hint be mentioned in the documentation or not?

I was invited to review some code. I've never done that before and barely know the project. Thus I'm following the README step by step. I log everything. The README says in its "Quickstart" ...
1
vote
2answers
79 views

Is using KDoc/Javadoc comments inside of a function considered bad practice?

I often find it helpful to use KDoc/Javadoc comments inside of a class or function instead of normal comments. IntelliJ colorizes them more obviously by default and, more importantly, allows ...
-2
votes
1answer
46 views

How should I list authors and their roles in doxygen comments?

Suppose I'm the first person write a proper Doxygen comment for a source file. Suppose also that there have been multiple contributors to the file - original author, previous maintainers, current ...
24
votes
11answers
6k views

The Don't Repeat Yourself (DRY) principle in documentation

Dave Thomas, the author of the Don't Repeat Yourself principle said: DRY says that every piece of system knowledge should have one authoritative, unambiguous representation. Every piece of knowledge ...
1
vote
1answer
101 views

Where would you place the working description for a function?

i like to think out a function using comments before writing it. I'd like to keep the information in the code as comments somewhere but i don't know where it should be kept. At the moment i keep it at ...
1
vote
1answer
57 views

Use case descriptions -- where does selection go?

I have a use case for which a user can perform a multiselection. I am writing the use case description and wonder: Should the selection action be documented as a trigger of the use case, or in the ...
0
votes
3answers
164 views

Is it good practice to put comment headers into each file?

I have an Unity project with countless of C# script files and I'm working on it solely. Although nobody else is working on it, I'm aware that some form of code documentation is crucial for my future ...
-1
votes
4answers
171 views

What is the Software Engineering equivalent of a traditional Engineering Change Order (ECO)? [closed]

What best practices do large software companies recommend when introducing a breaking-change to their software development process? Put another way, how do you best communicate these changes to fellow ...
0
votes
1answer
83 views

Code reference symbols in documentation, comments and pull requests?

I've seen method references in PRs and comments and documentation but it's unclear what the specific symbology means. E.g. ClassName#myMethod or ClassName::myMethod or what about ClassName::CONSTANT ...
2
votes
1answer
87 views

What types of documents should I include in a legacy software documentation package?

TL;DR: What would you look for in a collection of documentation when taking over an app to be run a larger scale than originally designed for? I've been tasked with writing documentation for an ...
2
votes
4answers
141 views

How can I keep track of which existing lines of code/text have passed some new review?

Firstly, this is a really tough topic to do searches for because you get a wealth of information on “code review”, which is different from what I’m referring to here. That normally refers to ...
0
votes
1answer
39 views

How to document attributes from legacy application

I have to replace an old application (Database, C++ UI) which is mainly for data administration, with on a new application (Same Database, Spring-Boot, Angular). We want to document how the ...
0
votes
1answer
67 views

Managing Documentation / Source Control for a Full-Stack Application Across Multiple Repos

TL;DR I have a moderately sized/complexity web application (Angular 11) in one repo and a standalone REST API (.NET Core 3 / C#) in another repo, and am trying to figure out the most efficient way to ...
0
votes
0answers
41 views

Open API documentation in function definition? - YAML verbatim vs JavaDoc

Open API [swagger] is a fancy way of writing REST API documentation, it looks like: description: user to add to the system content: 'application/json': schema: $ref: '#/components/schemas/...
2
votes
2answers
142 views

If logging in is not a Use Case, then what is it and where do I describe it?

I am writing a functional specification for a project and I wish to express the expected system behaviour in Use Cases. I have read a bunch of opposing opinions on whether "logging in" ...
-1
votes
1answer
46 views

How do you enforce API contracts across mutliple stacks?

For systems that are built on top of diverse tech stacks, including both static and dynamic types languages, what is in practice some ways to have the API contracts published and enforced? Some wiki ...
12
votes
4answers
1k 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
170 views

AMQP messaging: How to generate documentation 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
185 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
82 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
324 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
222 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
68 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
83 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
78 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 ...
36
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 ...
-1
votes
1answer
633 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
218 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
131 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
119 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
124 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
63 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
293 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
493 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
348 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
114 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
249 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 ...
5
votes
2answers
213 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
295 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
478 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
249 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
595 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
213 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
390 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
279 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 ...

1
2 3 4 5
13