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.
0
votes
2answers
21 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 ...
3
votes
2answers
62 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
85 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 ...
-2
votes
0answers
22 views
Documentation requirements for manual Agile unit testing [closed]
I understand that the expectation is that unit testing in an agile environment will be done using automated testing.
We have some legacy systems that are not using automated testing.
what level of ...
1
vote
2answers
120 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, ...
1
vote
0answers
70 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
98 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
46 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
95 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" ...
1
vote
2answers
68 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
54 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
107 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 ...
6
votes
5answers
242 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
185 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
118 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
146 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
123 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
92 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
97 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
129 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
172 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
36 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
53 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
70 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
292 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
85 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
41 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
112 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
225 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
29 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
220 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
87 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 ...
1
vote
1answer
54 views
How to avoid repetition in docstrings?
I find that in my code, many methods in a class or a set of related classes have quite similar arguments:
Arguments:
dt_start (datetime): Starting date.
Needs to meet complex requirements x and y ...
1
vote
2answers
65 views
The best practice for writing of examples
I have written some projects. I try to annotate or comment all possible (hard to say if correctly toward clean explaining).
I would like to write documentation for it, but I have problem with ...
5
votes
2answers
159 views
How much static analysis history should a company keep?
Supposing you work in a very large global company with lot of code at all levels (e.g. from embedded to mobile platform application code), and projects can last anything between 6 months to 5 years... ...
5
votes
1answer
119 views
How can I better document these data relationships/transformations?
I'm working on a project that uses RxJS to perform data transformations on varying sources of data, and I'm in the process of writing some documentation for it.
I want to find an effective way to ...
23
votes
1answer
2k views
Why does the documentation on some languages say “equivalent to” rather than “is”?
Why does the documentation on some languages say "equivalent to" rather than "is"?
For example, the Python Docs say
itertools.chain(*iterables)
...
Equivalent to:
def chain(*iterables):
...
10
votes
1answer
478 views
How to document a Ubiquitous Language?
Our company is in the process of converting a lot of manual business processes (and the associated institutional knowledge) into new enterprise software. The project is going really well, but as we ...
1
vote
2answers
243 views
Use a hash character or a dot when referring to methods and fields in software documentation? [closed]
Assuming I have this class (Java code only for the sake of example):
class Person {
private String name;
public void setName(String name) {
this.name = name;
}
}
When I write ...
0
votes
1answer
214 views
Docstring convention for Python __str__, __unicode__, and __repr__ class methods
What is the docstring convention in Python for the following "magic" class methods:
__str__
__unicode__
__repr__
Should I add docstrings for these? If yes, what should they say (for each)?
1
vote
1answer
283 views
How to document GUI screens transitions of a complex application
There is an application based on multiple screen model with pretty complex net of transitions between these screens.
It has some similarities to a web page or Football Manager like games. Its main ...
1
vote
3answers
781 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....
0
votes
0answers
44 views
Organising client-server projects
I am about to spin up a new development in my shop. It will be our first client-server application. It will be written for .NET 4.6 using C# and visual studio. WCF will be used for interprocess ...
4
votes
1answer
1k 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 ...
1
vote
0answers
92 views
Is there a good way to create an FAQ section within a markdown README.md [closed]
I have a small project where I want to put the FAQ into the main README.md page without having to fuss with manual formatting of it and ideally with collapsing sections to make it easy to scan the ...
0
votes
1answer
92 views
Should I document expected call-sequences when call-order matters?
In dynamically and weakly-typed languages*, I often find myself with structures like the following pseudocode:
class Stateful:
# [ various datamembers / attributes / properties / fields / etc. ]
...
1
vote
1answer
378 views
PHPDoc Comment, Class vs File
I am trying to standardise my code as much as possible, including DocComments, using PHPCS.
It seems that the PEAR standards contain two sniffs that require almost exactly the same tags appear in the ...
