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
51 views

For Java, are there any more modern/recommended forms of documentation, than just Javadocs? [closed]

I am currently in the early stages of developing a piece of Java software with another dev, and we are both wondering if there is a more up-to-date/recommended comment framework than Doxygen/Javadocs? ...
3
votes
2answers
216 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 ...
-2
votes
2answers
80 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 ...
1
vote
4answers
209 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 ...
35
votes
6answers
6k views

Methodology for documenting existing code base

I work as part of a team on an existing application that has no inline documentation, nor does it have technical documentation. As I've been working on various bug reports on the application, I've ...
3
votes
2answers
121 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 ...
11
votes
8answers
2k views

Commenting regular expressions

Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
4
votes
2answers
136 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 ...
4
votes
2answers
250 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
137 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 ...
2
votes
1answer
444 views

Describing JS program flow in @fileoverview

I have to edit other people's JavaScript code. The code usually loads some data from a Web API, generates a table, places it into the HTML page, and attaches some event handlers. Due to the async ...
5
votes
2answers
223 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
51 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 ...
3
votes
1answer
283 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 ...
2
votes
3answers
187 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 "...
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 ...
6
votes
5answers
378 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
154 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 ...
4
votes
1answer
2k views

Representing a user event in a flow chart

I was wondering which symbol should be used for representing a user event (i.e. button click). seems like it should suffice, but isn't a user click technically ?
0
votes
1answer
73 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
173 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 ...
10
votes
1answer
11k views

How do I represent a schema diagram of my MongoDB database?

I have a MongoDB database that I want to properly document its schema design. I know that MongoDB is a NoSQL database and is schemaless by nature, but I do enforce a schema through my application and ...
4
votes
2answers
3k views

How should I handle docstrings of subclass methods?

I have an abstract class structured somewhat like this: class AbstractQuery(object, zip_code): def execute(self): """ Retrieve information about a zip code The information ...
83
votes
13answers
12k views

Can commented-out code be valuable documentation?

I wrote the following code: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); ...
239
votes
16answers
44k views

What's wrong with comments that explain complex code?

A lot of people claim that "comments should explain 'why', but not 'how'". Others say that "code should be self-documenting" and comments should be scarce. Robert C. Martin claims that (rephrased to ...
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 ...
60
votes
12answers
16k views

Is there any logical reason to auto-generate code documentation? [closed]

Automatic documentation generation can be done with a variety of tools, GhostDoc being one of the more prominent. However, by definition, everything it generates is redundant. It takes a look at ...
105
votes
10answers
10k views

How to make a large codebase easier to understand

Suppose that I am developing a relatively large project. I have already documented all my classes and functions with Doxygen, however, I had an idea to put a "programmer's notes" on each source code ...
2
votes
1answer
121 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 ...
113
votes
4answers
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 ...
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 ...
3
votes
3answers
2k views

What norms/standards should I follow when writing a functional spec?

I would like to know what documents (ISO?) should I follow when I write a functional specification. Or what should designers follow when creating the system design? I was told that there was a ...
-1
votes
1answer
64 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 ...
3
votes
2answers
555 views

Documenting and handing over Source Code

I have recently left my previous student job as a part time developer for at small ERP management firm. During my time at the firm i have developed several modules for integration with the ERP ...
1
vote
2answers
298 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 ...
13
votes
7answers
29k views

What should I include in my class documentation header

I'm looking for informative class documentation format for my Entity, Business Logic and Data Access classes. I found following two formats from here Format 1 ///------------------------------...
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)...
0
votes
1answer
104 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 ...
11
votes
6answers
11k views

How to document business rules

I am wondering what would be the formal and the most commonly practiced method of documenting business rules? Also how do you document the UI specifications of development artifacts (e.g. Documenting ...
-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 ...
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. ...
5
votes
4answers
6k views

Should I use future or present tense when writing a design spec document?

I'm writing a Design Specification Document for a college project and wondering about the tense I should use. The development on the project has not yet started, I'm just writing the UI design section....
3
votes
1answer
129 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 ...
4
votes
5answers
15k views

Are High Level Design and Low Level Design documents needed to follow Agile development process?

Our team is developing a project using an Agile development process. All of our requirements are converted into product backlog items and task are broken down based on that. One of my team member ...
13
votes
8answers
3k views

Where to put code documentation?

I am currently using two systems to write code documentation (am using C++): Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen ...
4
votes
3answers
1k views

How can I convince my managers to enforce documentation standards?

I'm trying to convince another group in my company— that's about to hand code off to my group—that they need to provide more documentation in their source code, but they're treating it as a "nice to ...
5
votes
4answers
2k views

Keeping documentation / manuals up-to-date in a rapidly changing project

Background I work on a relatively large project (~570 KLOC) in a relatively small team (formerly 5 developers, now 2). Large amounts of code can appear and then vanish in months; for example, a few ...
5
votes
2answers
189 views

Seeking advice on system documentation

I have a rating engine (it is basically an algorithm) which when I started had no formal documentation. We have created a functional specification/decomposition which is our business level document ...