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
2answers
570 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 ...
8
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
847 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
428 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
728 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 ...
16
votes
6answers
5k 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
184 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
219 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
167 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.
5
votes
2answers
36k 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
388 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 ...
8
votes
3answers
1k views

How does one read RFCs and similar documents? [closed]

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
251 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 ...
7
votes
5answers
1k 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
535 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?
11
votes
5answers
2k views

Software Manager who makes developers do Project Management

I'm a software developer working in an embedded systems company. We have a Project Manager, who takes care of the overall project schedule (including electrical, quality, software and manufacturing) ...
-2
votes
1answer
251 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
321 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 ...
5
votes
7answers
751 views

In what stage of development should comments be written?

I'm a student working an internship at a larger company, writing small business apps in C#. I've noticed that I don't comment my code as I write it. Rather, I comment my code when I'm in the ...
-2
votes
1answer
194 views

What should I aware of , when preparing a document of website for later maintenance use? [closed]

The development team has finished a website and my duty is to prepare a document so that other programmers can maintain the website with ease. I have no experience in this and would like to ask what ...
2
votes
1answer
468 views

Why is it said that V-model introduces QA?

In several articles and books I learnt that "V-model introduced QA into SW development". I would like to understand the point of such statement, as from my understanding, V model activities ...
3
votes
1answer
125 views

How to automate the API Diff document? [closed]

We can use doxygen to do the documentation, but how can I do the API Diff? Any open source or free solution for that? Or I need manually prepare? Thanks.
5
votes
2answers
144 views

Seeking advice on system documentation

I have a rating engine (it is basically an algorithm) which when I started had no formal documentation. We have created a functional specification/decomposition which is our business level document ...
5
votes
2answers
417 views

Java code documentation in a separate docs file somehow mapped to a source file?

What would be a good alternative to inline Java documentation, i.e. can one have a separate docs file somehow mapped to a java source file? I have never liked huge comment sections littered in code. ...
2
votes
1answer
579 views

A better JavaDoc? [closed]

The standard JavaDoc template(Doclet) didn't change much until the recent JDK7. In my opinion, JDK7 template only made it even more difficult to browse. I looked at several third-party doclets, but ...
8
votes
3answers
720 views

Are XML Comments Necessary Documentation?

I used to be a fan of requiring XML comments for documentation. I've since changed my mind for two main reasons: Like good code, methods should be self-explanatory. In practice, most XML ...
8
votes
3answers
194 views

How to document experimental or incomplete APIs like @deprecated?

Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely ...
2
votes
1answer
535 views

Lua & Javascript documentation generation

I am in the beginning phase of create a mobile MMO with my team. The server software will be written in JavaScript using NodeJS, and the client software in Lua using Corona. We need a tool to ...
2
votes
4answers
473 views

Is extensive documentation a code smell? [closed]

Every library, open-source project, and SDK/API I've ever come across has come packaged with a (usually large) documentation file, and this seems contradictory to the wide-spread belief that good code ...
2
votes
2answers
1k views

What norms/standards should I follow when writing a functional spec?

I would like to know what documents (ISO?) should I follow when I write a functional specification. Or what should designers follow when creating the system design? I was told that there was a ...
2
votes
5answers
1k views

What are the benefits and drawback of documentation vs tutorials vs video tutorials [closed]

Which types of learning resources do you find the most helpful, for which kinds of learning and/or perhaps at specific times? Some examples of types of learning you could consider: When starting to ...
4
votes
4answers
174 views

Methods to Manage/Document “one-off” Reports

I'm a programmer that also does database stuff and I get a lot of so-called one-time report requests and recurring report requests. I work at a company that has a SQL Server database that we ...
4
votes
2answers
225 views

How to communicate within a company what is being Continually Deployed

I work for a small development company, 20 people total in the entire company, 3 in actual development, and we've adopted CD for our commits to trunk, and it works great, from a code management and ...
1
vote
2answers
164 views

How to correctly write an installation or setup document

I just joined a small start-up as a software engineer after graduation. The start-up is 4 year old, and I am working with the CEO and the COO, even if there are some people abroad. Basically they both ...
2
votes
4answers
225 views

What Does It Usually Mean for a Feature to be “Supported”?

I'm currently working some testing for a particular area of an application. I had to write some automated tests for a particular feature but due to the circumstances, this was not easy to do. When I ...
2
votes
1answer
3k views

What to put in a Stored Procedure documentation?

I was tasked to document our stored procedures. Target audience: Technical Purpose: To have a good documentation in preparation for migration. I'm assuming someone has already done it.
5
votes
2answers
3k views

How to document requirements for an API systematically?

I am currently working on a project, where I have to analyze the requirements of two given IT systems, that use cloud computing, for a Cloud API. In other words, I have to analyze what requirements ...
-2
votes
2answers
522 views

Specifying Author in Source Code in a Commercial Product

Usually there is an @author tag in API documentation (JavaDoc, PHPDoc etc). Is it acceptable to use this tag on every function you make in a commercial product?
4
votes
3answers
148 views

What level of detail to use in an interface members descriptions?

I am extracting interfaces from some classes in .NET, and I am not completely sure about what level of detail of description to use for some of the interface members (properties, methods). An ...
15
votes
5answers
10k views

Design documents as part of Agile

At my workplace, we face a challenge in that "agile" too often has meant "vague requirements, bad acceptance criteria, good luck!" We're trying to address that, as a general improvement effort. So, ...
5
votes
1answer
151 views

How to visually document interactive user interfaces for fast consumption

I'm writing documentation for some interactive Ajax user interface but instead of writing everything in words I would rather provide diagrams that are faster consumed than whole paragraphs of text. I ...
2
votes
2answers
333 views

What kinds of visual content, tables or diagrams might I want to include in my Project Architecture Document?

Besides logical and physical architecture diagrams, comps / mockups and tables for expected network load between components and various data schemas, what kinds of visual content, tables or diagrams ...
2
votes
2answers
1k views

How do I read API documentation?

I've been trying to read through the RoR API to try to learn things that the tutorial missed, and I haven't been able to follow it at all. The only time I've read documentation was when I needed to ...
3
votes
3answers
797 views

Extreme Programming - documenting implementation?

In extreme programming methodology, what artifacts/ can be used to document the implementation? I have used an activity diagram to document the design steps for each activity. I have read that for ...
3
votes
2answers
972 views

How to document and peer review design in scrum?

I am a relatively new developer in a small business (a team of 3 developers and an equally small QA branch) working on a medium-sized system. The current iteration is still under 100k lines of code ...
1
vote
3answers
12k views

Are there any good, open-source change request systems? [closed]

I have a need to make a somewhat custom change request system (very high auditing requirements). Instead of completely reinventing the wheel I was wondering if there's an open-source change request ...
15
votes
2answers
6k views

What standard superseded 830-1998?

I have been looking into how to document software projects more formally, and I have learned about IEEE 830-1998: Recommended Practice for Software Requirements Specifications. However, as you can ...
8
votes
4answers
2k views

Is functional spec a “design document”?

So I have been a bit lost in the terms, so first of all I present you what I have learned so far: System requirements specification - what users want, what the system should do Functional requirement ...
11
votes
7answers
520 views

Documentation degrading - how to deal with it?

Important: we have no issues whatsoever with source code documentation. This belongs to regular code audit and is kept up to date. Our problem is with developers documentation (or, "external" if you ...