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
vote
3answers
94 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
14 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
78 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
70 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
44 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 ...
0
votes
2answers
59 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
1answer
133 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
64 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 ...
7
votes
1answer
215 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
117 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
128 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
118 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
253 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 ...
0
votes
0answers
25 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 ...
3
votes
1answer
302 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
61 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
85 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
146 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 ...
2
votes
1answer
93 views
How to generate learning material from your work [closed]
Catalyst: Recently my team has been tasked with bringing in house a large software project that has been worked on for over 20 years. Some of the old development team is still around, and originally ...
2
votes
0answers
61 views
Standard for order of tags in PHP DocBlocks?
Based on the tags listed from this "standard", is there an order of the tags that people typically follow? Even if it's not something that has been entirely accepted, but something proposed? I am ...
5
votes
5answers
644 views
Debug function input vs expecting code users to read the documentation - How far do I go? [duplicate]
I could write an endless amount of debugging code to handle the various components of input for a function, check that the correct data types are used, make sure things are decendants of the proper ...
1
vote
4answers
141 views
How to keep documentation up to date and accessible [duplicate]
The problem: Documentation is in code in the form of docs, its in wiki websites, its written down on notes, in diagrams and issue management systems.
When documentation is so spread out, how does ...
10
votes
4answers
1k views
Why should comments / documentation of a JavaScript function include so much? [duplicate]
I was researching proper commenting practices for JavaScript and highly upvoted answer (+100) cites JSDoc-like commenting. JSDoc promotes comments like this:
/**
* Represents a book.
* @constructor
...
8
votes
5answers
342 views
How to prevent changes to an internal API from breaking other projects?
We have like 20 - 30 independent modules/solutions. Each of these has about 7 - 10 projects with different classes, components, etc. These are all used internal to our company.
Our problem is when ...
1
vote
2answers
186 views
When is documentation, unit testing, QA and refactoring meant to be done in a 2 week agile sprint?
The team I am working on is trying to do agile development with 2 week sprints. I think we must be doing something wrong however, as we have to work like madmen to get the features implemented in the ...
3
votes
1answer
72 views
Methodology for exploring APIs in dynamic languages
As a regular user of Standard ML and, to a lesser extent, Haskell, the following pattern is deeply ingrained into my "instinctive" approach to navigating and learning new APIs:
Understand the types.
...
22
votes
6answers
3k views
Explaining new or uncommon syntax in comments [duplicate]
As per the title, should I be explaining syntax that I use in my code when I have a reasonable expectation that a developer looking at my code in the future will not be familiar with it? Short caveats ...
9
votes
1answer
168 views
How to keep code examples in javadocs up to date
I'm working on a small library that provides implementations of basic, well known string metrics. Mostly for my own education. So development happens whenever I've got a bit of spare time.
Because of ...
95
votes
10answers
7k views
How to make a large codebase easier to understand for new programmers
Suppose that I am developing a relatively large project. I have already documented all my classes and functions with Doxygen, however, I had an idea to put a "programmer's notes" on each source code ...
6
votes
2answers
284 views
Is there something peculiar to Matlab or Mathworks that supports so much “undocumented” code?
I've been drilling into a lot of Matlab recently trying to interface with an in house algorithm engineer's work to modularize it for use in a test bench outside his suite of applications. I've come ...
0
votes
0answers
40 views
Is listing Types in documentation a code smell
I'm documenting a ruby application and looking closely at YARD. I like the increased structure provided over RDoc, but I'm unsure about the Type declaration. In YARD, you can do something like
...
2
votes
1answer
96 views
How to write proper documentation for references in a docblock? [closed]
I am adding documentation to PHP code using the phpDocs tool:
/**
* This is a summary
*
* This is a description
*
* @use This function is called here and here
*/
function doSomething(){
}
I am ...
1
vote
1answer
55 views
What information should go into file-level document block?
I primarily develop for Node.js. I got into a habit of putting a file-level docblock into all of my .js files. It looks something like this:
/**
* project-name
*
* Licensed under the BSD-3-Clause ...
5
votes
3answers
111 views
When should “should” be used in documentation? [duplicate]
I was just reading http://lasagne.readthedocs.org/en/latest/modules/layers.html and wondering about some documentation style questions. One of them was the use of the word "should".
For example:
...
0
votes
0answers
112 views
Interactive help in a statically-typed language with overloading
One of the nice features of IPython is that I can inspect a function.
In [1]: def inc(x):
...: """Increments a number"""
...: return x+1
...:
In [2]: inc?
Type: function
...
5
votes
4answers
179 views
What Type of Report or Documentation to Expect from my Programmers
First, I am not a programmer nor do I have any programming experience. I am an entrepreneur that had a website idea and hired programmers to custom build it. It has been going on for the last one year ...
1
vote
1answer
100 views
Documenting MVC JSON API
I've got an MVC5 application that we're using an a JSON API for various clients (mobile apps, other web applications, etc.) as well as a traditional web application. Controller actions that return ...
2
votes
2answers
248 views
Agile Scrum - Importance of requirement gathering and documentation and suggestions to improve
We are using agile scrum methodologies for developing and maintaining a product. Since we are a product company, we do not work with customer directly on day to day basis, but instead communicate with ...
1
vote
1answer
232 views
How can I find what Resources a Java EE container provides?
How can I find what "Resources" a Java EE container provides? Can I discover this programmatically, or is there documentation I should refer to? (Note that the Java EE tutorial is vague on this ...
0
votes
3answers
3k views
Who should write the Technical Design Document? The BA or the Developer? [closed]
I work as a Snr. BA in a large Manufacturing company and I've just implemented a new Requirements Management Process.
We have a large range of internal developers who in the past have never been ...
3
votes
1answer
860 views
How do tools facilitate writing functional specifications?
C2 wiki on functional specifications suggest that this can be facilitated by tools, how?
A Functional Specification is a list of demands and constraints intended to describe a product to be ...
2
votes
3answers
196 views
Documenting intent Vs knowledge
It is said you should document the intent of your function or class which I agree with. However recently this line became a little bit blurred when I was wanting someone to document why this ...
4
votes
1answer
118 views
What is the origin of the phrase “extirpated as a potential munition”
I recently came across this statement in the Perl documentation:
extirpated as a potential munition
derived from the sentence:
"Creates a digest string exactly like the crypt(3) function in the ...
3
votes
3answers
296 views
Should code comments explain the control flow?
Should comments explain how the application control flow works? For example, the relationships between classes, how this function is used by other functions, and what we are trying to do with these ...
3
votes
1answer
623 views
How do I write a REStful API's functional specifications?
I've been looking for answers about writing functional specifications for a software for a while now but I can't seem to find an answer to my specific case.
I think I understand the difference ...
1
vote
0answers
184 views
UML diagram for SSIS process
I'm trying to do some technical documentation and would like to include some diagrams to better explain the processes in the system.
The process I'm currently trying to describe is the following:
...
-2
votes
3answers
152 views
Affecting culture as a newly hired developer [closed]
I've been in my first professional position for about six months now, and so I am hitting what I suppose is the pretty typical moment:
Naievely perhaps, I think there's a lot of cultural baggage ...
6
votes
2answers
3k views
How should I annotate, that a class is immutable in Java?
I recently stumbled upon how useful immutable objects are and that e.g. if you pass elements to a constructor and your class should be immutable, you have to copy these elements if they are not ...
1
vote
1answer
113 views
Documentation of interfaces
I know how to document a function:
/**
* Prints a greet message to the web page
*/
function greet() {
echo "Hi!";
}
Or describe the usage of a variable:
/**
* @type string $name The user's ...
