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
2answers
202 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
159 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.
4
votes
2answers
30k 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
362 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
1k 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
229 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
533 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?
-2
votes
1answer
247 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
303 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
750 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
193 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
437 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
143 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 ...
2
votes
1answer
553 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
684 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
181 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
512 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
454 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
917 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
164 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
221 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
157 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
218 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
476 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
144 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 ...
13
votes
5answers
9k 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
329 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
938 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
741 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
911 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 ...
0
votes
3answers
11k 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
5k 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
515 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 ...
1
vote
1answer
550 views

How to document unlimited argument parameters?

In PHP you can have a function take an infinite number of arguments like /** * Do abc... * * @since 1.0 * @param mixed $arg1 Arg description * @return string ...
5
votes
5answers
824 views

Open source software with good code documentation to improve design skill [closed]

As I'm trying to get better at designing good software I'm wondering if there are out there good (as in well written) open source software with lot of code documentation that aims to explain details ...
2
votes
2answers
375 views

HTML in docblock comments?

In the PEAR standards there is no reference to HTML, if its allowed or not. http://pear.php.net/manual/en/standards.sample.php But I see some people use HTML tags like <kbd> and stuff.. So is ...
5
votes
3answers
1k views

How To Document an Object Oriented Design in Text

For my next project, I'm looking to document my Object Oriented design in simple text before jumping the gun to code it up. I want to do this for two reasons. I want to give proper thought to my ...
3
votes
2answers
389 views

Is it recommended to use DocBlock even if I'm not using phpDocumentor?

I'm developing a simple website for a client. I have read about phpDocumentor and DocBlocks, and I thought that documenting my classes and functions will be very useful. I'm almost sure I will not ...
3
votes
5answers
600 views

How do you keep track of the meaning of your SQL fields?

The more SQL fields I add to my tables and the more primary/foreign keys I add the more I lose the overview for specific fields for certain scenarios like Get/Add/Delete/Update data. I use SQL ...
15
votes
6answers
528 views

Are unit tests really used as documentation?

I cannot count the number of times I read statements in the vein of 'unit tests are a very important source of documentation of the code under test'. I do not deny they are true. But personally I ...
3
votes
3answers
879 views

Are there any standards for preparing a user manual of electronic device? [closed]

Are there any standards for preparing a user manual of electronic device? I am trying to prepare a manual for a device. However, I could not find any format. If I find, I will take this as guide for ...
3
votes
4answers
3k views

How to properly document functionality in an agile project?

So recently, we've just finished the first phase of our project. We used agile with fortnightly sprints. And whilst the application turned out well, we're now turning our eyes on some of the ...