Stack Exchange Network

Stack Exchange network consists of 175 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Visit Stack Exchange

Questions tagged [documentation]

Software documentation is written text that accompanies computer software. It either explains how it operates or how to use it, and may mean different things to people in different roles.

-1
votes
1answer
48 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
114 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)...
1
vote
1answer
47 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
33 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
192 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
73 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
51 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
90 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
109 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 ...
0
votes
1answer
252 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 ...
4
votes
1answer
201 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
152 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
100 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
73 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
69 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
277 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 ...
109
votes
4answers
13k 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
69 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 ...
2
votes
2answers
925 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
117 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
306 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
421 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
639 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
671 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
73 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
397 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
vote
1answer
609 views

Understanding use case levels

I've found out that there are 5 use case levels: Level 0 Cloud Level 1 Kite Level 2 Sea Level 3 Fish Level 4 Clam Cloud level lists only high level users goals such as "Manage files". Kite level ...
4
votes
4answers
255 views

Do I need requirement analysis if there's no client?

I think it happened to everyone, having side projects, trying to do something new and big in their spare time, or maybe having a little startup where everyone has clear in their mind what the software ...
4
votes
2answers
356 views

how to document the results of programming for non-programmers

I keep running into a problem at work, and I'm hoping that others know a solution either from personal experience or from best practices. I am not a programmer. I do, however, heavily use RDBMS ...
2
votes
2answers
108 views

Make sense out of automatic information gathered from legacy system

I have a legacy system I need to plan a migration for. It's mainly developed in Ingres+4GL (an old Ingres based form system). I have the following information: Data Structures (data base relations ...
1
vote
3answers
274 views

how to write good software design documentation for an old project with limited documentation?

Two months ago I joined a development team for implementing new features over a software that evolved over 10 years. The current state is that there is very few documentation and in order to develop a ...
-3
votes
2answers
127 views

What is a standard procedure while parallelising a serial code [closed]

I have a C++ serial code which simulates a physics algorithm. The C++ code is serially optimised. What is the standard procedure and documentation that is followed while parallelising the code or for ...
-4
votes
1answer
78 views

What non-essential files should be included in end-user package?

I'm working on a free software GUI application and we are considering what non-essential files to include in the end-user package Here are my thoughts of possible files we may want to include: ...
1
vote
3answers
178 views

Documenting a new feature

I have recently started working on a complex project and recently had a team meeting where a new feature was discussed. I am not happy with the current architecture, because the system is undocumented....
2
votes
1answer
124 views

When and why during software reengineering sometimes the document reconstructing is skipped?

While studying the book of Software Engineering by author Roger Pressman I came across this point about software reengineering , where it is written in the book that if creating documentation is time ...
2
votes
1answer
361 views

What is the difference between a man page and --help for a Python script?

I'm currently developing some Standard Operation Procedures for the company I work for. I'm starting with the very small examples; like scripts. There are currently several scripts being written in ...
3
votes
3answers
293 views

Is there a well known way to document the process done before writting any code?

What I Want to do I'm in a process of sketching, prototyping and brainstorming to know the possibilities the code will deal with and what kind of problems I could face while writing the code. And ...
1
vote
2answers
654 views

How to approach the understanding, documentation and validation of legacy code [duplicate]

I've been tasked with studying a Python code, which runs on an orchestrator, which schedule the launch of the code in correspondence of some events. The code imports some modules, and it's basically ...
7
votes
2answers
4k views

What to include in “technical documentation”

I have the task to write the "technical documentation" for a software which I was developing. One reason or another I have never done this before, I do have experience with SRS, but this is something ...
2
votes
1answer
202 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 ...
0
votes
1answer
57 views

Should usage examples in XML documentation be explicitly tested?

If usage examples are provided in XML documentation, should those examples be explicitly tested? /// <summary> /// Gets a collection of Foo objects. /// </summary> /// <param name="...
1
vote
1answer
1k 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 ...
10
votes
4answers
357 views

Include a link to relevant documentation in error message?

We create a commercial library and code examples that are being used by external developers. We have (closed, available to registered users) documentation that extensively explains how to use the ...
4
votes
2answers
142 views

README “Setup” section best practice?

In the SETUP section of my README, should I just link to instructions for each dependency like this: STEPS install Appium (guide) install XYZ (guide) Or should I reproduce all their instructions ...
3
votes
2answers
230 views

Should I show the association class in my class diagram?

For example I have a relationship like this: user (0..*) buys product (0..*) Which results in an association class, called sale, which has the userID and productID. Just for the question's sake, ...
4
votes
3answers
3k views

UML Class Diagram: How to describe method functionality?

Recently, we have learned about UML class diagrams in university and I began applying that knowledge to my work projects. However, I am still unsure how or where I am supposed to describe the ...
-2
votes
1answer
428 views

Software documentation steps

I am trying to write documentation for a project and I have trouble finding information about list of documents that need to be written. I know there are Vision and Scope, User Requirements, ...
5
votes
4answers
1k views

Is it consider bad practice to formally document implementation code?

PEP-8 clearly states which parts of your code should have documentation: Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public ...