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
3answers
369 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
170 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
580 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
216 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
394 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
166 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
346 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
110 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 ...
30
votes
2answers
1k views

Why aren't plain-text markup languages (like LaTeX or Markdown) more popular in the software development process?

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 ...
2
votes
1answer
931 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
65 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
102 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
289 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 ...
-1
votes
5answers
511 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 ...
14
votes
4answers
835 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
409 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 ...
37
votes
14answers
2k 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
167 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 ...
3
votes
5answers
594 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
123 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
83 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 ...
2
votes
0answers
86 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 ...
1
vote
1answer
9k views

Difference between functional and technical specification [duplicate]

I'm writing a specification for a project, and am struggling with separating functional specification from technical specification (see http://www.joelonsoftware.com/articles/fog0000000035.html). ...
2
votes
2answers
488 views

What information should be in the github README.md?

What information would you expect to see in the github README? Should everything go in the README? i.e. Introduction Installation Versions User Guide Implementation Testing Related Resources Or ...
1
vote
2answers
126 views

Is repeating links to the same class in a single javadoc comment a bad practice?

I'm currently writing an API and its documentation. For example I have something like this: public interface Event { } public interface Process { } public interface EventProcessor { /** * ...
2
votes
1answer
550 views

How to protect yourself as DevLead from political management games [closed]

As a developer/DevLead you've got your focus on developing software and you may be quite good in it. Developers are, however, in my observation often not so good at playing political games. This ...
0
votes
1answer
85 views

Maturity User Guide, Documentation and Ease-of-learning PHP-framework

I'm at the very start of a longtime running project with continual development. Because of that I'm hoping to make a good decision in which Framework will be right for this. Previously I've worked ...
0
votes
2answers
126 views

Documenting reports for end-users

I have an application that has about a dozen reports that provide totals and summaries of data in the database based on date ranges given as parameters. The application is near the end of user ...
1
vote
1answer
68 views

how to map controllers , models, and views as a todo list

Before starting on a current project I was wondering if there is a terminology for what I am planning on doing? Basically what I want to do is map out every object in layers such as all the ...
7
votes
4answers
2k views

How to document a project which is already developed?

I would like to know what options are available for documenting a project which has already been developed, as the developers who worked on didn't write even a single page of documentation. The ...
6
votes
1answer
225 views

Is there a de facto standard documentor for Javascript?

I'm trying to document my code using JSDOC3, that has a similar syntax to PHPDocumentator / Apigen. But is there a de-facto standard for Javascript inline documentation? I think Google Closure is the ...
0
votes
0answers
126 views

HDF vs NOSQl solutions

Hi I get a look in some scientific data stored in HDF5 format and I was wondering if there is any NoSQl solution that will reach the same performance in read/write as HDF5 . The data of my example ...
2
votes
4answers
2k views

Creating a coding standards document

I work in a control systems company, where the primary work is SCADA and PLC, along with other control systems stuff. Softwre development is not really something the company does, apart from little ...
41
votes
7answers
3k views

How do you keep track of what classes and functions your team has written?

When working on code, I face many of the same challenges that my teammates do, and I have written some helpful functions and classes, and so have they. If there is good communication, I'll hear about ...
1
vote
1answer
148 views

Documenting Function That Takes Random Parameters?

What's the best approach to creating documentation (displaying the function prototype if you will) for functions that take a variety of different forms in terms of parameters. Let's say there are 10 ...
2
votes
3answers
137 views

Preferrable Method to record Documentation

As any taught Software Engineer knows how important Documentation for good software projects is. Could you show me best practices for assure good documentation beside of JavaDoc comments? In my ...
2
votes
5answers
370 views

What is the best way to understand code in a project with null documentation?

It is our first game and we are a start-up. We had a programmer who suddenly is seeming to be a dead weight. Though we knew him personally we thought that he was as motivated as we are and hence I ...
4
votes
6answers
989 views

What is the best way to prove that in-code documentation is greater than extensive external documentation?

What is the best way to prove to my boss that in code documentation is greater than extensive external documents containing documentation and screenshots of code/ui? We have a group in the company ...
0
votes
0answers
68 views

What is expected in the documentation of a software project [duplicate]

I have about a month left to work on my final year project for college and between all my assignments and exams, I have to write documentation for it. On our college guidelines it states the ...
4
votes
1answer
503 views

Diagrams used to model the architecture and functionality of a website

I am attempting to understand what UML models/diagrams can be used to communicate a websites architecture. The model or models' purpose is to communicate the architecture and functionality of a ...
4
votes
1answer
367 views

Duplicating documentation on interface implementations/overrides good or bad?

So we have an interface like so /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos ...
4
votes
4answers
1k views

NoSQL and BIG DATA

I am doing an internship on Big Data technologies so I am new to this area. My question is about the use of NoSQL in the Big Data architecture. Do we need always to use a distributed storage (like ...
5
votes
3answers
121 views

XML Documentation for IoC Classes

I'm working on an application that uses Inversion of Control to achieve loose coupling between the Data Access and Business Layers. Having an ILoanApplicationRepository and a ...
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 ...
3
votes
3answers
216 views

Is it correct to exclude argument names from function prototypes?

I was recently creating a small technical documentation for an application. The document is to be used by newly hired programmers to get acquainted with the application. It is much friendlier than the ...
2
votes
3answers
538 views

UML diagrams for small projects

All of a sudden the need for proper formal documentation has become a thing in our organization. A lot of work I do are enhancements and addition to an existing system. Generally a quick fix or a new ...
4
votes
1answer
829 views

Does doxygen support templates for the HTML output?

I've documented my code for doxygen, but I don't want the default HTML it gives. I know I can customize it by providing custom CSS, headers, footers, etc. (like GNOME does), and how I can add common ...
3
votes
2answers
113 views

What's a good format for documenting hundreds of data feeds?

Several governments are starting to publish open data: datasets generated by the goverment, made freely available for citizens to use for value-added app development, analysis, and feedback. For ...
2
votes
2answers
458 views

How do I document a communication protocol on top of message queues and channels?

I'm working on a large project at the moment and I'm trying to document the communication protocol that sits on top of a message queue middleware. The documentation is intended for another ...