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

Is there some standard or virtually standard way to document code in a language agnostic and IDE agnostic fashion? [closed]

In java we generally do it the java-docs way and in js the popular method these days is vscode documentation using @param, @returns, @example etc but I would prefer if there were some language ...
Raven Danish's user avatar
0 votes
1 answer
202 views

Creating necessary documentation for maintenance staff when only Code repository contents can be relied on [closed]

Conditions: stable legacy prod system no Software Devs of the system are available anymore app is maintained by Engineers, who do not have the same software dev experience like the original Devs and ...
stack3r's user avatar
  • 125
1 vote
2 answers
152 views

What is an appropriate length for function names? [closed]

I'm writing a C++ class, CBookSpellDef which has the following methods: int GetIndexOf(const char *psz); char* GetNameAtIndex(int index) { return m_spellTypes[index].szName; } char* ...
AcinonX's user avatar
  • 467
0 votes
0 answers
36 views

Automated API Versioning

I did research about this and I'm facing with two challenges: how to handle version deprecation in my CI/CD pipeline, when we have more than one major versions officially functional and others ...
Hirbod's user avatar
  • 1
2 votes
2 answers
150 views

How to document a concurrent communication protocol for less theoretical people

We are developing a multi-user web-based application, where the users can join a "room" and a complicated handshake has to be set up between them, to be able to use a library on each ...
staccato's user avatar
-2 votes
1 answer
106 views

What is standard/considered best practice for the media used for different documentation? [closed]

I have just started my first position as a software engineer after finishing my degree, and, as warned, software is much different in industry than in academia. The startup that hired me does not have ...
Lavie's user avatar
  • 107
20 votes
6 answers
5k views

What are better ways of indicating "insert actual value in place of the placeholder value" in documentation?

We develop an online booking system and it may be embedded in customer websites in an iframe. It is very simple to use, you just include a JavaScript file on the page and call the initialisation ...
Kyohei Kaneko's user avatar
24 votes
11 answers
7k views

Why and how to write clear code comments and when will documentations be needed beyond code commenting?

I am learning programming on my own following standard programming language textbooks. I come from a math background. I learned C on my own, but never really got to the more advanced portions. I ...
Seth's user avatar
  • 381
1 vote
1 answer
147 views

Should I include an actor to represent the database in a use case diagram? [duplicate]

I'm working on the documentation of software management system. That system can be linked with an e-commerce website to get financial data directly. For example when a transaction will be made it will ...
Laila Ejaz's user avatar
0 votes
1 answer
91 views

Where to keep assets for documentation generation as to not clutter the main repository

I have a large C++ project I'm hoping to release publicly soon (it is currently an internal development at work). We have a large auto documentation setup which uses doxygen and sphinx, however our ...
Chris Gnam's user avatar
-1 votes
2 answers
74 views

Java: Autogenerating documentation for Strategy Pattern with lambdas

Situation Object MyObject needs to be sent to one of our downstream systems depending on the enum value of its field myField. public class MyObject { private MyEnum myField; public MyEnum ...
downwash's user avatar
2 votes
7 answers
459 views

Is there a term that describes the property of being synchronous vs asynchronous?

Is there a term that describes the property of being synchronous vs asynchronous? The term that most naturally comes to mind is "synchronicity", however I only see this term being use in ...
Rylander's user avatar
  • 139
4 votes
2 answers
280 views

Term for type information from C Source Code

I'm writing a code that extracts information about functions (prototype) and types (enum, struct, typedef) from a C source file. This is to augment the type information about a particular function or ...
Marco's user avatar
  • 377
28 votes
6 answers
10k views

Is documenting a big project with UML Diagrams needed, good to have or even not possible?

I developed a big(ger) project, which is in use already and grows, gets altered, fixed, etc. every week. Until now I am the only developer. Since the team has to grow, also we will be more developers ...
Edgar Alloro's user avatar
1 vote
5 answers
125 views

Should docs of extended methods include documentation of the base method?

Let's say some method of a parent class is reimplemented in a child class. This child method is intended to do the same that the parent method, with a minor change. In this case, in the documentation ...
NonoG's user avatar
  • 21
1 vote
2 answers
554 views

How to document pass-through parameters

I'm currently working with a pre-existing class (not written by me) that has functions which call other functions, passing through the parameters to the helper functions. Sometimes there are layers to ...
WhoDatBoy's user avatar
  • 123
3 votes
3 answers
752 views

Documenting my abstract class/interface - what is important?

I am still an beginner/intermediate programmer at best so apologies if I misuse terminology. I work with SCADA software for my job, specifically Ignition by Inductive Automation. It's made for rapid ...
Brian Karabinchak's user avatar
4 votes
2 answers
546 views

Situation where software engineers effectively take role of product (unwanted, but for practical reasons)

My team owns several services. One is our primary focus: an accounts service. We have a plentiful stream of feature work and tech debt to address there, and everyone (engineers, product, design, ...
Andrew Cheong's user avatar
3 votes
2 answers
268 views

What's a good workflow for including mechanical sketches in code comments?

My team writes a lot of Python code in PyCharm to do quick simulations and calculations for our mechanical engineering work. Often, we'd like to include a little image (a hand drawn sketch, CAD ...
Emily Conn's user avatar
1 vote
2 answers
240 views

What does "legacy signature" mean?

I see the term legacy signature a lot in the documentation of programming languages. For example in the php documentation : Passing the separator after the array (i.e. using the legacy signature) ...
Hicham Jerdaoui's user avatar
-3 votes
1 answer
118 views

Technical Debt in frontend development [closed]

I have recently joined in a new company as a frontend developer and I got access to their current repository which is made in ReactJS. I can see that current team is not very experienced in reactJS ...
San's user avatar
  • 1
2 votes
2 answers
173 views

How to document external libraries that have been adopted into an existing codebase?

I have been using an external library for a while now. Unfortunately, it stopped receiving updates, and has since been adopted into my codebase. The issue is the library was poorly documented in the ...
Nicholas Ficara's user avatar
1 vote
0 answers
73 views

How sould I document dimensions of a pointed-to buffer?

This is a "doxygen style/etiquette" question. I have a function which takes, say, an int *buffer. Now, buffer is actually a multi-dimensional array, with different dimensions in each axis, ...
einpoklum's user avatar
  • 2,496
1 vote
2 answers
1k views

How to document a NoSQL document-based data model?

How do you document the logical data model of a document-oriented database like MongoDB? For relational databases, Entity-Relationship diagrams or UML class diagrams are used. What is the practice for ...
ssn's user avatar
  • 71
0 votes
2 answers
234 views

How to automatically manage documentation

Our project consists of a cluster of microservices (let's say 20, mainly JS & PHP) that are communicating among themselves and exchanging data (via MQ) among themselves. Also, clusters have API ...
Petr Bělecký's user avatar
2 votes
1 answer
526 views

Is using the doxygen @file command counter-productive?

I'm having a dilemma regarding whether or not to use Doxygen's \@file (a.k.a. \file) command. On the one hand, it's somewhat useful for you to use @file, and IIANM, Doxygen relies on its presence ...
einpoklum's user avatar
  • 2,496
-3 votes
1 answer
565 views

How to document business processes/rules inside Python code and export them?

I'm in a project that computes a lot of metrics with Python code. We need to document how each metric is computed, inside the code, for readability, and outside, in some Wiki, for non-technical people....
Be Chiller Too's user avatar
3 votes
1 answer
729 views

UML activity diagram modeling for multiple input/output Program

I have to create a overview documentation for a simple PLC (programmable logic controller aka industrial automation controller) program (happens to be written in Step 7 but not really important). The ...
Ari's user avatar
  • 33
-2 votes
1 answer
91 views

Do I need to write Scenarios if I use Event Storming? [closed]

Event Storming is a great method to understand the business processes. Scenario (Use Case Specification) also describes the business process. They both do one thing. But when documenting, the Event ...
Ngọc Nguyễn's user avatar
9 votes
4 answers
579 views

How to document alternative code I considered but didn't go with due to performance?

I write code in R, and often find myself attempting to optimize the code for better performance. In a given script that tackles a specific problem, I test different code alternatives and compare them ...
Emman's user avatar
  • 209
0 votes
1 answer
634 views

Documenting classes with doxygen (I want a birds eye view of the code but also want documentation)

When I code in plain C there is quite a beautiful interaction between headers and c files in terms of documenting the code. I tend to add the documentation on the cc files (and yes I am aware that ...
Makogan's user avatar
  • 261
-1 votes
1 answer
150 views

What is the name of the documents that describes changes and implementation?

In our development process, we have documents for each task/feature that describe API changes API logic Data flow (if needed) Database changes How client should interact with new/modified APIs Other ...
tia's user avatar
  • 975
1 vote
1 answer
181 views

Given-when-then template for docstrings

Tests can be very nicely written down using the given-when-then style. Are there similar styles / templates for describing methods and classes in docstrings? To clarify: There are many sites which ...
gebbissimo's user avatar
4 votes
2 answers
151 views

Documenting dynamic constraints in API data

Background I work for a company that provides installation instructions for solar panels on roofs. We also provide an API where external parties can provide roof input and preferences, and return an ...
Yuri's user avatar
  • 157
-2 votes
1 answer
104 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 ...
underthevoid's user avatar
-1 votes
1 answer
69 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 ...
DocWriter's user avatar
2 votes
1 answer
1k 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 ...
aldokkani's user avatar
  • 129
43 votes
7 answers
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" ...
jjk's user avatar
  • 549
1 vote
2 answers
345 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 ...
Matt Robertson's user avatar
-2 votes
1 answer
774 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 ...
einpoklum's user avatar
  • 2,496
24 votes
11 answers
7k 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 ...
iwis's user avatar
  • 349
1 vote
1 answer
112 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 ...
Richard Bamford's user avatar
1 vote
1 answer
122 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 ...
user2132190's user avatar
2 votes
4 answers
4k 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 ...
Junes's user avatar
  • 33
-1 votes
4 answers
216 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 ...
Matthew Nielsen's user avatar
1 vote
1 answer
138 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 ...
GoldFlsh's user avatar
  • 147
2 votes
1 answer
184 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 ...
Paul Sender's user avatar
2 votes
4 answers
589 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 ...
Deep Thought's user avatar
0 votes
1 answer
106 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 ...
Tobias Otto's user avatar
1 vote
1 answer
352 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 ...
Kurtis Jungersen's user avatar

1
2 3 4 5
13