Questions tagged [documentation]

Software documentation is written text that accompanies computer software. It explains how the software operates, how to install it, how to use it, and other resources for help.

Filter by
Sorted by
Tagged with
2
votes
2answers
459 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
259 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
167 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
228 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
1k 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
171 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
119 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
899 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
235 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'...
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
269 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
154 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
388 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
91 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
196 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
436 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
468 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
895 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
117 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
145 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
3answers
112 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
254 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
700 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 ...
22
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): ...
14
votes
1answer
3k 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 ...
3
votes
2answers
3k 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 ...
1
vote
1answer
1k 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)?
2
votes
1answer
847 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 ...
4
votes
4answers
6k 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....
9
votes
1answer
11k 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 ...
0
votes
1answer
112 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. ] ...
4
votes
1answer
3k 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
111 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
211 views

Standard for order of tags in PHP DocBlocks? [closed]

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
684 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
2k 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
5k 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
910 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
338 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 ...
4
votes
1answer
84 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. ...
25
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
277 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 ...
104
votes
10answers
9k views

How to make a large codebase easier to understand

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 ...
7
votes
2answers
583 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 ...
2
votes
1answer
190 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
114 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
148 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: ...
-1
votes
1answer
228 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
256 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 ...