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
0answers
14 views
How to write understandable documentation on XML layout
I am building an application that uses XML documents for communication and I have defined tags, some are mandatory, some are optional. Basically, the XMLs are part of an API.
How could I create a ...
0
votes
2answers
71 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
votes
0answers
29 views
Attribute-driven design documentation confusion regarding subsection Design methods and standards
I am working on a school project, which is a simple hospital management system. For this project, I have to write up an ADD document for it. I am stuck on one section in particular. It is called ...
1
vote
0answers
41 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
48 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
45 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. (...
0
votes
3answers
58 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
84 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
101 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
123 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
316 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
100 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
54 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
100 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
70 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
56 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
115 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
246 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
192 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
122 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
148 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
126 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
100 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
150 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
177 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
59 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
71 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
295 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
86 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
42 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
125 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
228 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
31 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
244 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
89 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
55 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
66 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
162 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
128 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
519 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
277 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
232 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
303 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 ...
2
votes
3answers
858 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....
