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

4
votes
1answer
1k 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
171 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
569 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
92 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
146 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
75 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
4k 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
291 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 ...
3
votes
4answers
4k 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 ...
42
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
161 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
149 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 ...
3
votes
5answers
502 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
1k 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 ...
4
votes
1answer
607 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 ...
6
votes
1answer
1k 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
129 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 ...
40
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
221 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
667 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
2k 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
141 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 ...
3
votes
2answers
723 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 ...
2
votes
2answers
367 views

Is there any taxonomy/language to describe user interfaces?

I'm currently researching the options which I have, to build an 'Online Help System'. This system should offer the user information about dialogs - which consists mainly out of forms. So my main ...
3
votes
3answers
386 views

How to document events?

Code documentation is usually related to a piece of code, be it small (method-level) or larger (class- or namespace-level). However, it is always about the inputs and the outputs of that piece of ...
8
votes
1answer
321 views

Are there any empirical studies about the effects of commenting source code on software quality, maintainability and developer productivity? [closed]

I am an advocate of commenting on source code and documenting software products. It is my personal experience and observation that working on source code that is rigorously commented has helped me in ...
5
votes
2answers
500 views

At what stage of a project should documentation be done?

I was assigned to fix some issues in a PHP project. Later on, I was asked to implement some new features, which I did. The project neither uses any framework nor does it use OOP. It lacks a proper ...
2
votes
1answer
145 views

Is MSDN / Azure Active Directory information available in different formats?

I'd like to read the documentation of Azure Active Directory on my kindle (or similar device), but don't want to use "Print to Kindle" for each and every page. Is the Microsoft documentation for this ...
1
vote
2answers
5k views

Deliverables in a software development project

Following a standard framework of project management, for a software development project we will provide deliverables (documents and software) at the end of each month : My question is: From May ...
15
votes
6answers
1k views

Can you claim that your product is fit for purpose when it uses OSS software which does not guarantee it?

I am working on a product for a client that must be valid and fit for purpose. It's built on a LAMP stack (PHP/Cake), so there's GPL, MIT, PHP, APACHE licenses: "AS IS" BASIS, WITHOUT WARRANTIES ...
0
votes
2answers
499 views

Software Requirement Specification documentation by professionals

I just wanted to know what is the significance of SRS(Software Requirement Specification) in programming? and what are the techniques used in preparation of an SRS .. also who writes the SRS.. is it ...
6
votes
1answer
1k 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 ...
3
votes
1answer
573 views

documentation of typescript code [closed]

my question is rather short: How do I document typescript code properly? I found out that for projects becoming bigger and bigger, it is important to look at a function and immediately know ...
1
vote
1answer
352 views

What is Context Diagram in a SRS?

I am learning how to write a System Requirements Specifications, and most of templates I have seen talk of a Context Diagram. What exactly is a Context Diagram?
0
votes
1answer
524 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 ...
14
votes
6answers
4k views

Git-friendly spreadsheet format? [closed]

We're trying to move our project documentation process from Google Documents to a set of self-hosted Git repositories. Text documents are Git-friendly enough, since we usually do not need any fancy ...
6
votes
3answers
179 views

How to refer to specific areas of code in documentation?

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
4
votes
2answers
178 views

How to properly include field validation in a Software Documenation

I'm developing a software documentation in a project, and much of it are just CRUD or CRUD based functions. As you can imagine, a lot of the rules are constraints about fields validation, things like ...
3
votes
2answers
2k views

Describing requirements in SRS - use cases?

I do not have the access to the IEEE standard and information on the net are contradictory. Can I capture user requirements in SRS using use cases? Or I should keep use cases separate as they are more ...
3
votes
2answers
155 views

Wiki/markup in enterprise as documentation [closed]

Why it is less common to use wiki/markup in enterprise as documentation? They use Word document instead. Wiki/markup are in text format, which is version control friendly.
3
votes
2answers
20k views

What is the difference between technical specifications and design documents?

What are technical specifications? Are they the same as design documents. If not, what is the difference and some examples?
1
vote
2answers
333 views

Formalizing a requirements spec written in narrative English

I have a fairly technical functionality requirements spec, expressed in English prose, produced by my project manager. It is structured as a collection of UI tabs, where the requirements for each tab ...
6
votes
2answers
911 views

How does one read RFCs and similar documents?

RFC: Request for Comments (RFC) is a memorandum published by the Internet Engineering Task Force (IETF) describing methods, behaviors, research, or innovations applicable to the working of the ...
1
vote
2answers
207 views

Questions to ask a 3rd party API provider [closed]

I'm due to meet with a developer/sales person from a new 3rd party resource we're about to start using. The main topic I'll be interested in, is their API as I will be the developer making use of it ...
6
votes
5answers
896 views

Is a functional spec a part of the System requirement spec?

I wonder, sources like wikipedia or templates I found shows that Functional spec is a part of System requirement documents. I always thought that SRD is just overall decsription of the system, with ...
6
votes
7answers
527 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
1answer
73 views

Is there such a thing as a specification-code framework?

I've been googling for a while and can't fathom why this doesn't exist yet. By a specification-code workflow I mean a system which links code to it's specification. For example I could be looking at ...
-2
votes
1answer
228 views

SpecFlow/Cucumber - Documenting available steps [closed]

Our company is looking at implementing BDD in our .NET application. Specifically, SpecFlow. We can foresee a large number of common steps being created ('Given a customer', etc), so what methods have ...
6
votes
2answers
279 views

What's a good length for Javadoc for a class that is say 800 lines long?

I'm doing a code-review on someone's code for class. The class is about 800 lines long, contains a good dozen of functions but the description is like 1 line long. I'm wondering, generally ...