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
39 views
How to add multiline comments for field of the struct in Go? [on hold]
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
38 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
187 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 ...
3
votes
3answers
216 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 ...
2
votes
1answer
94 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
119 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
47 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
75 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
169 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
324 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 ...
2
votes
1answer
79 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
48 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
99 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
46 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 ...
0
votes
1answer
63 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
48 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. (...
1
vote
3answers
108 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
103 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 ...
3
votes
1answer
109 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
126 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, ...
4
votes
1answer
327 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
104 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
66 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
108 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
72 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 ...
2
votes
1answer
66 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]...
2
votes
0answers
121 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
280 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
199 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
126 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
150 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
134 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 ...
58
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 ...
1
vote
2answers
97 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
116 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
45 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
170 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
182 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
37 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
74 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
76 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
303 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
87 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
44 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
152 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 ...
8
votes
3answers
232 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?
0
votes
0answers
37 views
Requirement/analysis documents in branch-per-branch versioning enviroment
Our ALM is implemented in TFS where for every team project we employ branch-per-feature approach. Each feature may contain multiple backlog items.
For each team project we need to maintain master ...
-2
votes
2answers
311 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 ...
2
votes
1answer
92 views
Does license have to be in text format?
Does a software license have to be in text format? I am thinking of adopting the MIT license to my software. I have a documentation in HTML format, which is distributed together with the software, and ...
