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

-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 ...
5
votes
7answers
746 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
188 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
401 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
510 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
644 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
171 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
479 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 ...
1
vote
4answers
420 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
893 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
796 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
156 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
217 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
153 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
211 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
2k 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
2k 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
420 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
141 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
8k 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
150 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 ...
1
vote
2answers
319 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 ...
1
vote
2answers
842 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
679 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
838 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
9k 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 ...
14
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
1k 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
509 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
458 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
792 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
329 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
967 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
337 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
577 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
512 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
799 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 ...
2
votes
4answers
2k 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 ...
7
votes
4answers
16k views

What is an “implementation plan”?

I was recently given the task of creating an implementation plan document. When I asked for an example of one that I could look at, I was told to look at the Project Plan that had already been created ...
2
votes
2answers
102 views

Is gettext appropriate for internationalizing user help documentation?

On my project, we have po files to internationalize/translate various labels, error messages, button-text etc. We also have separate po files for the entirety of our help documentation, which is ...
10
votes
7answers
1k views

Where to put code documentation?

I am currently using two systems to write code documentation (am using C++): Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen ...
21
votes
4answers
994 views

Is BDD actually writable by non-programmers?

Behavior-Driven Development with its emblematic “Given-When-Then” scenarios syntax has lately been quite hyped for its possible uses as a boundary object for software functionality assessment. I ...
3
votes
2answers
276 views

Content of AUTHORS file

GNU recommends making an AUTHORS file to list the authors and contributors of a program. But how many "levels" of authors and contributors should the file contain? E.g. if I write a program foo that ...
4
votes
5answers
1k views

How to make sure the application source code has a proper documentation for new programmers? [duplicate]

Possible Duplicate: How much documentation is enough? Do you know how the big IT company like IBM, Microsoft, or google make sure their application source code has proper documentation for ...
9
votes
3answers
575 views

How do you keep track of complex business rules outside of code?

I'm interested in seeing how other people do this. Especially in situations where multiple different clients are using the same software base with slightly different business rules. What kind of ...
9
votes
7answers
927 views

How do professional software development teams deal with design complexity in non-trivial projects?

First, I realize this question may by somewhat long and vague and I apologize for this. This is probably a basic problem with a short name to anybody who's "got it", but as I find myself lacking in ...
9
votes
3answers
483 views

What is the connection between literate programming and the semantic web?

I was (casually) researching semantic / ontology based approaches to technical documentation, when I stumbled upon this gem: Literate Programming and the Semantic Web are ideas from different ...