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
0answers
16 views

What are the main components of a system and their relationships? [on hold]

I have designed a management system for a medical practice and I am writing the design specification and I am kind of stumped by what to write. It says to include an overview of the architecture of ...
-3
votes
0answers
51 views

Create a master login web page? [closed]

I want to create a master login page for owncloud,roundcube and phpfox. It means I want to create a simultaneously login page(single) for all softwares at once. That means when you log on with that ...
1
vote
1answer
121 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
83 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
157 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 ...
1
vote
2answers
68 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() ...
17
votes
4answers
827 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 ...
0
votes
2answers
84 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. ...
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
79 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 ...
5
votes
4answers
111 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
98 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
42 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
45 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
94 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 ...
0
votes
1answer
35 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 ...
0
votes
1answer
58 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 ...
2
votes
1answer
67 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 ...
1
vote
1answer
110 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 ...
1
vote
2answers
126 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 ...
1
vote
3answers
99 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 ...
3
votes
3answers
373 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 ...
6
votes
4answers
409 views

How to categorise information in end-user documentation?

One of the greatest piece of documentation I ever read is the TeXbook by Donald Knuth—the manual of the TeX typesetting system, and I used it in my first analysis. As far as I can tell, the type of ...
4
votes
3answers
121 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 ...
1
vote
2answers
211 views

When to write software project documentation on code [duplicate]

I usually write my software projects in java, and I am still a bit confused as to when to document my classes, interfaces and methods. There are two ways: 1) Write documentation after declaring or ...
1
vote
2answers
130 views

Tender vs. Requirements vs. Solution Design

Conventionally, which of the above documents is deemed to hold the most weight when it comes to system acceptance? I recently had a conversation along these lines: It was argued that the initial ...
1
vote
1answer
83 views

Is there a tool to generate multi-goal procedural instructions? [closed]

As a user: When I have good instructions to follow I'm sure I could do just about anything. With poor instructions I end up frustrated, wasting time and probably giving up. The type of instruction I ...
2
votes
3answers
302 views

How to explain to non-programmer to build my Visual Studio source code in “Release” mode?

I'm writing documentation for some software that I wrote. Specifically, I'm writing a guide to installing the software. I'm delivering the source-code to my client, so I expect that they will want ...
0
votes
1answer
103 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 ...
19
votes
6answers
2k views

Old programmer disappeared. About to hire another programmer. How do I approach this? [closed]

After spending over one year working on a social network project for me using WordPress and BuddyPress, my programmer has disappeared, even though he got paid every single week, for the whole period. ...
-2
votes
1answer
162 views

PDF to doxygen - how to do it? [closed]

I have a big pdf with the documentation for a project and I need to render this to doxygen (so take each function from the pdf and write it out into doxygen). Any suggestions on how to do this ...
7
votes
1answer
308 views

Creating an effective C++ library website and documentation

Creating a C++ library also means documenting it so that others can use it, and that documentation can vary dramatically in quality. How should a website for a C++ library be structured so that it ...
3
votes
1answer
99 views

Marking specific pieces of drastically changed open source code

I have taken a small chunk of open-source code, around a hundred lines, and found that for whatever reason, I have modified it so drastically that my end result has essentially no resemblance to the ...
5
votes
1answer
288 views

Which concepts are pertinent to plan a “end-user documentation” strategy?

I am writing a lot of software and I feel that writing good documentation is very difficult. Since I am not aware of any structured theory about software documentation I started to organise my ...
-1
votes
1answer
90 views

Is there any standard for design document [closed]

This question is purely from academic point of view. As part of the software engineering lab, a design document is to be created after generating the SRS. Is there any standard for creating the design ...
1
vote
3answers
204 views

How do you decide how much business requirements documentation you need and how to structure it? [closed]

In the past couple of years, I've worked on two projects. The first one, we used a very agile methodology. It was very much developer driven. As such, changes were very quick and rapid. Code quality ...
6
votes
5answers
399 views

Maintaining good form while learning new technologies

I find that I have to learn new technologies fairly regularly as a contractor in order to keep competitive. However, I also find that (not only, but especially) in these circumstances, I tend to end ...
5
votes
5answers
234 views

Hyperlinked, externalized source code documentation

Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code, rather than as a separate document? Given the expansive ...
0
votes
2answers
251 views

How to write comments to explain the “why” behind the callback function when the function and parameter names are insufficient for that?

How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on. I ...
5
votes
4answers
498 views

Should user documentation include screenshots? [duplicate]

This question focuses on user documentation, not on code documentation. I just finished my software project, and the people I work for are expecting me to write user documentation, describing ...
2
votes
2answers
214 views

Design document for project in C

I have had some experience in documenting the design for project developed in OOP languages. I made classes and used class diagrams to showcase the overall design structure of the implementation when ...
2
votes
1answer
240 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 ...
3
votes
2answers
167 views

How do you validate need for documentation?

I once was on a project where a non-tech manager had the team spending half of every hour documenting what they just did so that someone with zero understanding of the tech would be able to understand ...
-1
votes
1answer
66 views

What are the most crucial categories of content to organize into an internal developer portal in a large company? [closed]

I have been tasked with organizing all of the company's internal content currently spread around sharepoint, a markdown reference manual and confluence into a single cohesive and usable portal in ...
37
votes
12answers
2k views

Documentation in OOP should avoid specifying whether or not a “getter” performs any computation?

My school's CS program avoids any mention of object oriented programming, so I've been doing some reading on my own to supplement it -- specifically, Object Oriented Software Construction by Bertrand ...
5
votes
3answers
184 views

Importance of diffing and merging for design specifications documentation

The context of this question is choosing tools for writing design specifications for software projects. These documents will be written and maintained by architects and developers, I'm not talking ...
-3
votes
1answer
192 views

Version Control for One Man Dev Team? [duplicate]

I recently began work at a small company as a lone software developer. Before I came no true documentation/version control/etc. was in place. The best they have is Microsoft Word documents and Excel ...
14
votes
5answers
1k views

Is a well written documentation a good enough reason for learning a programming language?

I am learning Python currently which wasn't part of my college curriculum. I was asked in an interview why I chose Python and I replied that it is easy to learn and the documentation is very well ...
2
votes
2answers
382 views

What do you call parentheses operators?

In most programming languages documentation where they talk about operators +-*/=<> they also include ()[] as operators. There are unary operators, multiplicative operators, additive operators, ...
70
votes
13answers
3k views

What are examples of comments that tell you why instead of how or what? [closed]

First of all, in this question I'd like to stay away from the polemic on whether source code commenting is good or bad. I'm just trying to understand more clearly what people mean when they talk about ...