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.

learn more… | top users | synonyms

0
votes
1answer
32 views

Referencing official documentation in source-code documentation

What are your preferences for referencing official documentation (like a white paper) for an algorithm from comments in the code that implements it? I'm trying to decide between two methods, as ...
4
votes
3answers
469 views

Is it Typical for Large Software Companies to Not Document or Refactor Code? [closed]

I have begun working at a large software company and was assigned to a project that is over a million and a half lines of code. It's part of a program suite that is sold to clients (not an in-house ...
-2
votes
0answers
47 views

selecting a code base documentation tool - free or otherwise [closed]

so we have a large PHP application with areas of javascript, css, html and of course php/mysql that I'd like to document. I'd like to throw in diagrams that I scan or snap a photo of, etc.. I'd also ...
3
votes
2answers
128 views

How to do documentation for code and why is software (often) poorly documented?

There are some good examples of well-documented code out there, such as java api. But, a lot of code in public projects such as git and internal projects of companies is poorly documented and not very ...
2
votes
5answers
159 views

How viable is to create a mini documentation inside the source code

So, I work as a developer. We are a small team. The majority of the people (everyone except the project manager and the senior developer) are still in university. We have very flexible work hours, ...
3
votes
5answers
555 views

How do you keep track of the meaning of your SQL fields?

The more SQL fields I add to my tables and the more primary/foreign keys I add the more I lose the overview for specific fields for certain scenarios like Get/Add/Delete/Update data. I use SQL ...
0
votes
2answers
123 views

How should I document a multi-tier application?

I have to create a documentation structure for a legacy application, and I'm not sure of how to organize it. Documentation goals: List of use-Cases Program flow for each of the use cases. ...
3
votes
2answers
176 views

Is it customary for software companies to forbid code authors from taking credit for their work? do code authors have a say?

The company I work for has decided that the source code for a set of tools they make available to customers is also going to be made available to those customers. Since I am the author of that source ...
0
votes
1answer
109 views

Your thoughts on Best Practices for Scientific Computing? [closed]

A recent paper by Wilson et al (2014) pointed out 24 Best Practices for scientific programming. It's worth to have a look. I would like to hear opinions about these points from experienced programmers ...
1
vote
1answer
32 views

What does backup procedures and troubleshooting guidelines mean for a system

I am writing the documentation for a piece of software which I have made but I don't understand what it means in some aspects. It asks me to write about backup procedures but what exactly does this ...
9
votes
6answers
478 views

How to use unit tests as a source of information?

A colleague of mine was once at a seminar about agile development, where he heard it is possible to use unit tests as technical documentation. Something like using unit tests as an example of how to ...
5
votes
3answers
359 views

Should I follow an open source project's documentation patterns even if they are bad?

I've considered making modules and the like for various languages and other open source things. Where documentation is not specified but rather is communal de facto standard or entirely ad hoc; should ...
-1
votes
1answer
39 views

Where can I find better designed nginx documentation? [closed]

Actually I have a sub-question here:"Is Nginx official documentation opensourced?" Nginx is a good software, but I found its official documentation(http://nginx.org/en/docs/ really hard to read, ...
1
vote
3answers
116 views

How to consider the login function collecting requirements of an application? is it a user requirement?

I am working on an application that expected to the user logs in when the application is started (as for example it is in Skype: the user open the application and appear to him a login mask when he ...
0
votes
0answers
15 views

Scala/SBT - Documenting Configuration Change for Releases

I'm trying to collect different ways of managing configuration across multiple environments. I have a requirement to document configuration changes for the deployment plan. Dev values are defaults in ...
12
votes
9answers
722 views

Code Documentation First?

Has anyone ever tried creating a complete code documentation first, before actually writing the code? I was thinking about this earlier because I thought it would help to write a concrete interface ...
-1
votes
1answer
82 views

What's the verb for “currying”? [closed]

As per Wikipedia, partial application is a process (noun) that fixes a number of arguments to a function, and currying is a technique (noun) that transforms multi-arg functions in a way that it ...
6
votes
6answers
498 views

Commenting regular expressions

Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
0
votes
3answers
133 views

What goes within the Architecture Overview of a Design Specification?

I have designed an management system for a medical practice and I am writing the design specification and I am kind of stumped by what to write for a section. It asks for me to write about the ...
3
votes
3answers
688 views

Are there any standards for preparing a user manual of electronic device? [closed]

Are there any standards for preparing a user manual of electronic device? I am trying to prepare a manual for a device. However, I could not find any format. If I find, I will take this as guide for ...
0
votes
1answer
446 views

Are there differences between Functionality and Functional Requirements [closed]

I'm writing some documentation in a project in a tool. In this tool of mine, and write in specific area, I have here use Case, Business Rule, N-Diagram Types, and Functionality and Functional ...
4
votes
3answers
975 views

What wiki/document system do you recommend for knowledge-management? [closed]

I'm founder of a web-site called Now.in. I wrote all programs by my-self at first. And we are going to run a start-up company. More people will soon get involved. Some know-how/overviews only exist in ...
11
votes
7answers
3k views

Are wikis really appropriate to store documents for software development?

Everybody knows that well-documented software development leads to success. However, it usually means that not only plain text but also binary content will be involved in the document, such as a UML ...
1
vote
1answer
143 views

As an lone, Agile (PXP/PSP) developer what is the proper structure for a formal project post-mortem? [closed]

Question: As an lone, Agile (PXP/PSP) developer what is the proper structure for a formal project post-mortem? Scenario I'm using a PXP methodology (which is a blend of extreme programming and the ...
3
votes
2answers
92 views

How to document a file format specification [closed]

For a project, I need to work with varying types of files from some old games and related software--configuration files, saves, resource archives, and so on. The bulk of these aren't yet documented, ...
0
votes
3answers
164 views

Has there been any formal proof that documentation in general is incomplete and obsolete to a certain grade? [closed]

I'm a web developer and I'm currently once again in a situation where a partly clueless ops department requires a "complete" documentation required for technical support of our application by a ...
17
votes
4answers
1k views

How to document the high-level structure of a Java program?

Background: My collaborators and I are writing an article for an academic journal. In the course of our research, we wrote a simulation program in Java. We want to make the simulation program freely ...
1
vote
2answers
72 views

How to write descriptive conditionals for ifs?

I've gotten into the habit of using excessively descriptive names. In addition, I've also gotten into the habit of creating the conditions for ifs like so: bool user_is_female = user.get_gender() ...
0
votes
0answers
40 views

How would you collect the ideas that needs to be discussed during time [duplicate]

What is the best way of collecting and/or keep tracking of ideas/issues that needs to be discussed in details and during the time? As an example, imagine within the team you're brainstorming about ...
0
votes
1answer
89 views

Documentation required for commissioned software (product) [closed]

The company I work for has commissioned a software company to produce a compliance software for several big companies. As part of our contract it is required of them to provide us with src code and ...
2
votes
4answers
225 views

Document overall business architecture [closed]

I’m looking to document my business’ overall system architecture. I want to capture what system/s everything starts in, what systems it flows into and why, and where everything ends up. As part of ...
5
votes
4answers
150 views

Keeping documentation / manuals up-to-date in a rapidly changing project

Background I work on a relatively large project (~570 KLOC) in a relatively small team (formerly 5 developers, now 2). Large amounts of code can appear and then vanish in months; for example, a few ...
1
vote
2answers
114 views

How to document self explanatory setter functions? [duplicate]

Often boolean setters are pretty self-explanatory, like setLogErrors($bool). I do see some benefit of providing some additional information in the documentation, in this instance maybe where these ...
0
votes
2answers
56 views

Frameworks/methodologies for documenting functional/use case scenarios and mapping them to code base [closed]

Is there an established framework or methodology for documenting functional or use cases and mapping them to units of code? E.g. assume you are a new developer hire assigned to work on an ...
0
votes
2answers
47 views

Multiple documentation issues in a single bug

It is clearly a bad practice to incorporate several issues in a single bug. It is not convenient, hard to maintain, difficult to keep track of what is done and what is not, etc. But does all this ...
-2
votes
1answer
131 views

Best practices in Application's flow diagram [closed]

I make web applications, mostly MVC, object oriented and database enabled. I always have trouble going back to project after a few months of release and work again. I don't even remember what I made ...
2
votes
1answer
111 views

Outline for technical software documentation

Say I have a software project for which the technical documentation should include A license document A list of used terminology An introduction about what the software does A short quick-start ...
0
votes
1answer
40 views

Am I allowed to use text(snippets) from the iOS Developer Lib for my documentation?

At the moment, I create a Java-Wrapper for Apples *.pkpass-Files (Passbook). Since I need to parse a JSon-File, I planned to add java doc to every field, so one know what exactly this field is in the ...
10
votes
7answers
886 views

Where to put code documentation?

I am currently using two systems to write code documentation (am using C++): Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen ...
0
votes
1answer
71 views

How to organize software document for the same application supporing both iOS and Android

I have to write software project documentation for an application which will support both iOS and Android. Each platform has its specific features and the mobile app design and requirements are almost ...
5
votes
5answers
257 views

Documenting higher-level concepts

I will be leaving my current project in a few days, and as part of securing my knowledge I have been asked to add comments to the code wherever I feel that can add value. The problem I am running ...
39
votes
6answers
2k views

“I”, “We”, or Neither in code documentation

I find myself writing (hopefully) helpful comments in code (C++) documentation of the type: The reason we are doing this is... The reason I use "we" instead of "I" is because I do a lot of academic ...
1
vote
1answer
113 views

Use of # in answers/documentation when referring to methods of a class

When looking through Java documentation or answers for Stack Overflow / programming forum questions, I often see people referring to methods like String#format, Object#clone etc, rather than ...
5
votes
1answer
716 views

Splitting documentation between docstrings and sphinx

I'm using a combination of docstrings and Sphinx to document my Python programs. With Sphinx's autodoc, I can write a lot of documentation into the source as docstrings. Is there any standard for ...
38
votes
6answers
1k views

What should I do to leave a job professionally? [duplicate]

Given that the current employer knows and has been given appropriate notice ahead of time, how can a programmer make a clean job transition from his old job? What things should the programer consider? ...
14
votes
11answers
862 views

What should you leave behind for your successors?

Assume that you're a sole developer leaving a job. What kind of information/material, outside of the code itself, should you create and leave behind for your replacement? An obvious answer is ...
2
votes
1answer
244 views

How to find classes that use certain DB tables

Problem: I'm asked to prepare a document where all our DB tables are listed and I'm supposed to list all Controllers that uses these DB tables for read and another list for Controllers that do write ...
1
vote
2answers
146 views

Documenting/defining data structures in Python

What is the preferred way to document the contents of and logic behind dynamically generated data structures in Python? E.g. a dict which contains the mapping of a string to a list of lists of ...
4
votes
3answers
124 views

Would adding an @beta doc-comment tag be useful?

When a function has reached the end of its life, we add a @deprecated tag into its doc-comment to notify other developers that they should stop using this function, and then a couple years later it's ...
0
votes
1answer
115 views

How do I include Implementation and Usage Documentation in one file

There are two types of documentation. One type, the Implementation Documentation, contains information about specific implementation of a construct (eg. Class, Method, etc.). It is targeted to the ...