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

7
votes
4answers
479 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
125 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
322 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
165 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
92 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
337 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
133 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
176 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 ...
8
votes
1answer
506 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
113 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
330 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
vote
3answers
244 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
417 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
264 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
276 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 ...
6
votes
4answers
726 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
306 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
249 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
203 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
75 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
193 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
237 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 ...
4
votes
2answers
605 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
4k 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 ...
0
votes
3answers
496 views

How to document program flow so the outcome looks professional? [closed]

I have designed a simple website on paper. Now I want to produce a professional-looking document for my customer to approve. How can I do this? I've tried Visio, but it seems horribly ...
5
votes
2answers
174 views

how to pluralize 'special' terms e.g. class names

Quite often I find myself referring in text to objects which have strict naming conventions e.g. Java objects, processes, services. I find myself in a dilemma over how to pluralize these names. It ...
1
vote
1answer
1k views

Converting from web to PhoneGap

I was going through the PhonGap Documentation about how to package your HTML/JS/CSS to a platform specific "native app". They have maintained separate documentations for the separate Cordova versions ...
2
votes
1answer
324 views

What is the best way to track / record the current programming project you work on? [duplicate]

I have been in this problem for long time and I want to know how it's done in real / big companies project? Suppose I have the project to build a website. Now I divide the project into sub tasks and ...
5
votes
4answers
550 views

How to keep your programming resources, tips, tools and snippets handy and easy to find? [closed]

In my everyday work and on my free time, I tend to discover/learn/find pieces of information that can be really useful if used at the right moment but also really easy to forget and/or to find again ...
4
votes
2answers
195 views

How do you create documentation when there is none? [duplicate]

I have recently inherited a large, legacy system with a complex codebase that has a lack of documentation. I'm the sole internal developer embedded with the core users, taking some responsibility from ...
1
vote
3answers
444 views

How can I apply Readme Driven Development to an ongoing project?

I'm assigned to a project where the goal is to update an existing software. This software was developed in a totally ad hoc manner, which means that any documentation generated is outdated, confused ...
2
votes
1answer
113 views

Ported Functions Licensing

I have found several functions in python 2.7.2 to be very useful and I recreated them in C++ for my own uses. How do I properly give python credit for them? Do I even have to? I never actually looked ...
33
votes
3answers
2k views

What roadblocks face the development process in using plain-text markup languages as opposed to, e.g., Microsoft Word? [closed]

I'm currently an intern at a government contractor and am getting the (obnoxiously unavoidable) feeling that Word is the de-facto standard in the software development process. Its binary format makes ...
4
votes
1answer
2k views

What is the general format of a Software Design Specification?

I'm trying to document a piece of software I wrote in detail. An SAS is too high level and doesn't cover the API. I found several examples of an SDS online, but I don't see a trend in their format. ...
2
votes
0answers
89 views

Set of specific values implementation vs. using some sort of generic set with advanced checks

I am working on a set implementation in JavaScript currently. This should kind of simulate generics as known from Java or C#. I need a mutable version of that (allows for adding/removing set values) ...
1
vote
3answers
104 views

Adding correct documentation for a method

I have method like this: methodA(someParams) { do some initializations,etc; call methodB(someParams); } methodB(someParams) { do work; if blah then raise exception::FileNotFound if ...
6
votes
4answers
320 views

Are the technologies used in an application part of the architecture, or do they represent implementation/detailed design details?

When designing and writing documentation for a project an architecture needs to be clearly defined: what are the high-level modules of the system, what are their responsibilities, how do they ...
0
votes
5answers
715 views

Named output parameters vs return values

Which code is better: // C++ void handle_message(...some input parameters..., bool& wasHandled) void set_some_value(int newValue, int* oldValue = nullptr) // C# void handle_message(...some ...
15
votes
4answers
950 views

Documenting mathematical logic in code

Sometimes, although not often, I have to include math logic in my code. The concepts used are mostly very simple, but the resulting code is not - a lot of variables with unclear purpose, and some ...
8
votes
4answers
422 views

Should we be looking out for lying code?

This is referring to a discussion in an answer and the comments of this question: What's with the aversion to documentation in the industry?. The answer claimed that "code can't lie" and thus ...
38
votes
14answers
3k views

What's with the aversion to documentation in the industry?

There seems to be an aversion to writing even the most basic documentation. Our project READMEs are relatively bare. There aren't even updated lists of dependencies in the docs. Is there something ...
0
votes
1answer
191 views

Are there elements common to nearly every SRS?

An SRS is a staple of any serious contract work, and it can be incredibly dull for those who've never had the misfortune of needing to read one through in one go. I'm writing a series of document ...
4
votes
5answers
702 views

Does relying on intellisense and documentation a lot while coding makes you a bad programmer? [duplicate]

Is a programmer required to learn and memorize all syntax, or is it ok to keep handy some documentation? Would it affect the way that managers look at coders? What are the downside of depending on ...
2
votes
0answers
42 views

How to document legacy code (shell scripts)? [duplicate]

I got involved into a project where we are taking over a bunch of legacy code. Code is basically shell scripts and PL/SQL packages/procedures/functions. There is no documentation how the code works ...
1
vote
3answers
167 views

What document should describe usage of a third party library in a project?

A customer of my employer has recently requested new features for some legacy code, and since the authors of the program are no longer here, I've been assigned to implement the new features. I've ...
0
votes
3answers
86 views

Requirements Analysis Communication

How can I convert this requirement into one requirement: For columns where there are just numbers, numeric sorting will be used. For columns that have numbers and letters, alpha-numeric sorting will ...
1
vote
0answers
89 views

Is there a unified source code documentation generator? [duplicate]

I'm currently working on a client's project that involves programming in multiple languages. It has gotten to the point where the amount of source code for each language has grown to such a large ...