Stack Exchange Network

Stack Exchange network consists of 174 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

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.

4
votes
3answers
2k 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
245 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 ...
1
vote
1answer
388 views

How to add multiline comments for field of the struct in Go? [closed]

I faced with need add big comment for one of field of my struct, but I don't how to make it more idiomatic and graceful. You can see my versions, but, I think, it's unpleasantly to see. Any ...
0
votes
1answer
329 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
767 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
2k 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
132 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
473 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 ...
0
votes
0answers
465 views

Documentation Structure in Software Development Life Cycle documentation

In creating documentation for a project's life cycle, is it better to have all decisions and choices (including their resources such as images) placed in the same document, or is it better to ...
-3
votes
1answer
512 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
286 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
421 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
108 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
61 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
197 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
73 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 ...
2
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
61 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
236 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
699 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
154 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
148 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
444 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
135 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
101 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 ...
3
votes
1answer
436 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
81 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
184 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
0answers
303 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
417 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 ...
2
votes
2answers
268 views

Who should write technical documentation?

At first, I thought that the people writing the code should also document it. But there are reasons why this might not be true. A person who is new to the code could ask the right questions which ...
0
votes
5answers
201 views

Best format for design document? [closed]

I have an open-source project which requires me to create mathematical models to compute some things. I have to analyze some data to decide which model works well and determine the range of errors ...
1
vote
3answers
164 views

Is it important to write documentation in different formats?

We are developing a series of tools for our internal usage (only). We are writing the documentation in parallel with the development progress. Is it important to provide different documentation ...
4
votes
2answers
179 views

How do you adapt to changes to product specifications during development?

Problem Changes to product requirements/specifications during the development cycle are inevitable in a professional setting. In particular, I'm constantly dealing with changes to the specification ...
59
votes
3answers
5k views

Name of a program's startup/initial loading window?

I am writing user documentation (an SOP) that involves third party programs that I am trying to describe well. One such program is a server that offers little indication of it's startup besides a ...
2
votes
2answers
380 views

Is it poor practice to have dynamically updated docstrings?

When I'm creating a docstring, sometimes I want to refer to a value, for instance: def try_download(data, path): """Tries to download ATTEMPTS times, catching socket errors.""" Where ATTEMPTS is ...
2
votes
1answer
165 views

Extendable reference Software Architecture Document: good idea or not?

I've been tasked with writing SAD's for our current two projects and there are many more coming, all similar although different in small ways, mostly technical (they all have a similar requirements) ...
1
vote
0answers
53 views

Tips on reading undocumented code? [duplicate]

This summer I got my first position as a programmer (intern), but it has been a disaster. Before the internship they misled me; they didn't tell me they were developing Django apps and told me to just ...
2
votes
1answer
608 views

Documentation for unit tests

I have a small project written primarily in C++ which is documented with Doxygen and tested with a unit testing framework (Google Test in my case, but that doesn't matter). I wrote several test cases ...
3
votes
2answers
223 views

Should I document overloaded operators in C#?

So I have been working on a C# Matrix library. I've been documenting it really good so far. The thing is I don't know if I should document my overloaded operators, I mean, it is kind of obvious, isn'...
0
votes
0answers
55 views

Formal documentation - frequent Support-Cases

I have the task to document support cases for some Interfaces, which happen on a frequent base. This documentation is for the stakeholders: Developers for a new Interface Domain Exports Technical ...
23
votes
7answers
3k views

Release first or document first?

I've been working on a project for a couple years now, and I'm starting to gather a decent user base. I've created a project page with some basic documentation, but it's really not much more than a ...
1
vote
0answers
205 views

Shared pointers across threads in UML for class and sequence diagrams

How does one represent shared pointers across threads in UML for class diagrams and sequence diagrams? I especially want to document the ownership of the memory even though it's accessibility (a ...
1
vote
1answer
132 views

Dividing software into requirement layers

In order to be able to create better documentation, better tests and to start using the just gotten to know requirement traceblity matrix I'm trying to understand the different software requirement ...
1
vote
4answers
372 views

How to mark/track features in code?

After some time in every project sooner or later you will need to find a feature in it a fix it or extend it so I was wondering if there is already a system or a convention for marking those features ...
1
vote
2answers
89 views

Implementing something partially vs providing simple documentation?

I often encounter the following program while programming. There is a "partial" solution to a problem, which provides all the functionality that is necessary, but the documentation explaining said ...
1
vote
0answers
84 views

Should I use RFC 2119 in interface documentation?

RFC 2119 defines several terms, including MUST, SHOULD, and MAY, for use in standards documents, particularly those relating to networking protocols such as IP and HTTP. These terms are widely used ...
0
votes
2answers
370 views

is there a standard for documenting requirements interview

We're university students taking a course in information systems engineering. We have project and we've had a meeting with the teacher playing the role of a dentist and a helping girl playing the ...
9
votes
3answers
454 views

Is it bad practice to add external links in documentation?

Often I find myself solving bugs by finding the answer on Stack Overflow. Is it bad practice to add a snippet of why I did what I did and then add a link to an article or page from the web?
-2
votes
2answers
772 views

Where can I find software project deliverables/ documents to help me professionally document my projects? [closed]

Hie guys. I have never been employed in the software development industry and when I do projects I usually just draw non-standard diagrams or used use case diagrams and class diagrams. This time a ...