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
7
votes
2answers
5k 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
379 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
59 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="...
4
votes
2answers
2k 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
359 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
143 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 ...
2
votes
2answers
268 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, ...
3
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
472 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, ...
6
votes
4answers
2k 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 ...
6
votes
4answers
779 views

What is the antonym to “legacy code”? [closed]

I am writing a software documentation and I need a antonym to "legacy code". Is there any established word for the antonym to "legacy code"? I'll need this antonym to describe that code which was ...
10
votes
4answers
3k views

Is there a standard for documenting a program's high-level architecture?

I am an amateur developer and all my programs up to now were simple enough to be documented within the code. While reading the code it was clear what I was doing such and such action (my standard test ...
9
votes
4answers
5k views

Best practice to mark a method that is called via reflection?

Our software has several classes that should be dynamically found via reflection. The classes all have a constructor with a specific signature via which the reflection code instantiates objects. ...
1
vote
1answer
63 views

Should I doxygenate implementation files in a library of mine, in addition to the headers?

I'm in the process of writing Doxygen comments for this library of mine; it's a header-mostly C++ library, but it does have some code which gets linked rather than included. For that code, which has ....
6
votes
2answers
158 views

Keep documentation version the same as project version

In addition to this question Should Git be used for documentation and project management? Should the code be in a separate repository? I want to ask if it is recommended to keep the documentation ...
2
votes
2answers
137 views

Is there a standard way to refer to items inside a menu when writing documentation?

At several times in the past while writing software documentation -- including user manuals, user stories, bug reports, test cases, and emails to users/colleagues -- I've needed to be able to refer to ...
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 ?
3
votes
1answer
108 views

How to document logical proofs against race conditions?

Specific Background I'm writing a library to extend the async backbone of a language with cooperative multitasking. (The language is Hack, but C# also implements async-await with Task, if the concept ...
0
votes
1answer
388 views

Technical Design document and external agency

My company is recruiting an external agency to do a site redesign/development (agency has not been selected yet). Regarding the technical design document, should my company produce that document or ...
3
votes
2answers
1k views

How to document REST API before coding

My team is working on a web application using Micro Service Architecture and Angular + Spring MVC. We follow Agile development. For each story, we create few implementation and test tasks. Documenting ...
0
votes
3answers
178 views

What is the need for a cookbook as opposed to having just a reference manual? [closed]

What suggestions would you make to write a cookbook to use a distributed database? Does having a tangible end goal enough to distinguish a cookbook from a reference document? What else should I ...
1
vote
0answers
56 views

Adding documentation after modifying the code

In our TFS (Version 14.102.25423.0) I can click Browse on home page, then under Browse Server, pick my project and hit Navigate. Once inside my project, I see tabs like Home Code Work Build ...
4
votes
3answers
4k views

Release notes for first version

I understand what to include in ordinary release notes - there are many questions and answers relating to that. What should I include in the first set of release notes, i.e. for the very first ...
0
votes
1answer
500 views

Is it appropriate to use docstring `return` and `args` sections to specify HTTP statuses and URL parameters?

I'm working on a web application project which uses Tornado as the web frontend. Currently, I'm in the process of writing up docs and adding docstrings to the code base with Pydoc. As a web API ...
0
votes
1answer
409 views

How can I create a combined UX and Functional Spec?

Our organization has been clamoring for a more organized spec-making process. At the moment, we use a combination of UX Specs (created in a wireframing tool and published as PDFs), and Functional ...
7
votes
5answers
1k views

What is the importance of the vision document and how it helps development?

I'm a developer that works alone, and recently, searching for what kinds of documents I still could benefit, even though I don't require anything formal, I've read that one document that still is ...
4
votes
3answers
4k views

How to describe the architecture of a software product?

I'm working on my CS Masters thesis at a company which does user interfaces in the field of embedded devices. As part of that I am developing a library for integrating a certain device. My C++ library ...
3
votes
1answer
135 views

How to document a Software whose requirements are poorly managed? [closed]

Let's say I have a complex software product about which the information or knowledge is scattered all over the organization that built it. There are requirements and features about which even the ...
0
votes
2answers
661 views

Documenting embedded C code

I am starting a startup and myself and my partners are having trouble keeping up to date on each other's code and how to implement their functions. Our code is very well commented, but each of us have ...
-3
votes
1answer
888 views

Flowcharting a Get-ter

I'm not quite sure of the proper flowchart notation for returning an object/value from a function (I'm also looking for some quick tips on proper flowcharting notation in general, if anyone notices ...
3
votes
2answers
423 views

Is expecting the API user to implement an UnsupportedOperationException okay?

I'm writing a handler for download/import of data. After inserting data to the database, several import jobs can be called, but usually it is just one. So there are two methods to get the import job(s)...
6
votes
3answers
628 views

How important is documentation?

How important is a documentation? or a spec for that matter? I've been writing software professionally now for about 5 years. Each new job I start I am more often than not faced with spending a few ...
3
votes
1answer
115 views

Documenting variables in a Python module

I am writing a Python module that uses Numpy. I am trying to follow the Numpy docstring format. In many of my functions, the same parameters show up. It seems repetitive to explain what they are in ...
2
votes
1answer
62 views

What quality attribute would be favored using a rich search algorithm?

I'm working on an architecture document based on quality attributes. I'm trying to explain our search algorithm based on tags, historics and some bi information as a way of favouring a quality ...
0
votes
2answers
217 views

Should an internal Software Documentation Wiki have private pages?

I'm working on the creation of a software and product documentation in a wiki format. It will include the documentation for all the company products. After some research, we decided to use the ...
1
vote
0answers
85 views

How should I approach documentation generation for my FOSS library? [closed]

I've published a small FOSS library (link below, but what it does is not very material to this question), on GitHub. It doesn't have releases yet, but it's quite usable and (sort of) tested. Now, I ...
3
votes
1answer
1k views

Where is the OpenSSL documentation?

I've noticed alot of hatred about OpenSSL because of it's lack of documentation. And all advice and guide about the library must be passed around our people in song and story. I always doubt myself, ...
1
vote
1answer
63 views

How to preserve parameter names when using bind to define new methods

I'm writing javascript object that wraps REST requests. For every operation on the server there is a method that accepts the parameters for the request and a callback that will receive the results. (...
6
votes
3answers
237 views

How to document URLs and interaction between pages

We're developing a web application that is now growing to quite a few pages, all dealing with complex data and rather complex interactions between pages. For instance, the login flow encompasses the ...
4
votes
2answers
1k views

Should we include external services in a deployment diagram

I am designing a Deployment diagram and a Component diagram for an existing Java EE application. The app has integration with 3 external systems through soap web services and ftp. I am including ...
4
votes
1answer
184 views

Why was the warning about % formatting toned down in newer Python docs?

The Python 3.1.5 docs refer to the % style formatting as "Old String Formatting Operations" and provide this warning that it may be removed: Note: The formatting operations described here are ...
1
vote
2answers
155 views

Is it my job to enforce my preconditions?

Say I have a function that takes some arguments that fall under a bunch of constraints, e.g. one of them has to be an integer, another has to be a string of length at least 10, et cetera. In general, ...
6
votes
2answers
490 views

Executable documentation

I like asciidoc, resp. asciidoctor, for documentation purposes. It is way better than MS Word and integrates better with source control compared to tools like Confluence. Furthermore, I am aware of ...
4
votes
4answers
163 views

Generation of logic tables from if conditions

Suppose I have a large, multi-line case statement, which checks several variables before returning a final value. case when (foo='bar' OR foo='foo') AND (bar='foo') then 200 when (foo='jar') AND (...
1
vote
2answers
102 views

How can I tell when the Angular2 online documentation (or any website) changes?

I'm trying to keep up-to-date with the latest-greatest from Angular2, in part by carefully reading the official online documentation. Is there a way to be notified or at least to figure out relatively ...
2
votes
1answer
655 views

Requirements with units in Software Design Document?

I am new to the software design lifecycle and the various processes that it consists of. I was taught/told recently that units should not be included in the SDD because the software cannot "test" ...
0
votes
2answers
85 views

Should I include an explanation about the used framework in a programmer documentation?

In my intership I used the D3.js framework to visualize data, now at the end of the internship I'm going to write a documentation about the project as a whole. Only few people in my team have been ...
3
votes
1answer
274 views

Name of notation used when documenting command line parameters

Often, command line parameters are documented using a vaguely EBNF-ish notation such as the following: The output of dir /? on Windows: DIR [drive:][path][filename] [/A[[:]attributes]] [/B] [/C] [/D]...
3
votes
2answers
515 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 ...
10
votes
5answers
421 views

Using different patterns for similar features

I'm the sole developer on a project that, like for any software project, may be taken by somebody else in the future. Let's say I used the pattern X to implement feature A. After developing and ...