Stack Exchange Network

Stack Exchange network consists of 174 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Visit Stack Exchange

Questions tagged [documentation]

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
4answers
373 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
90 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
98 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
385 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
454 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
791 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
114 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
109 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
74 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
218 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
477 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): ...
12
votes
1answer
2k 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
2k 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
786 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
758 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 ...
3
votes
3answers
4k 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....
7
votes
1answer
9k 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
151 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
107 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
2k 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
110 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
157 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
665 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
1k 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
808 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
304 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. ...
24
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
262 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 ...
101
votes
10answers
9k 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 ...
7
votes
2answers
562 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
176 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
106 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
142 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
1answer
209 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
242 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
170 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
629 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 ...
3
votes
2answers
217 views

Should my application's README be for developers or users

My application is meant to be used by regular everyday users, but may also me modified freely by developers. These two audiences (users and developers) require different information. Should my README ...
1
vote
1answer
535 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 ...
1
vote
3answers
10k 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 ...
4
votes
1answer
2k 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
216 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 ...
3
votes
1answer
132 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 C ...
4
votes
3answers
384 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
2k 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 ...
-2
votes
3answers
177 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 on ...
14
votes
2answers
9k 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 ...