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

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
374 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
138 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
6k 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
146 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
311 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
717 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
609 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
697 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
7k 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
4k 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 ...
7
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
474 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
320 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 ...
6
votes
5answers
743 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
266 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
801 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
288 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
555 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
491 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
686 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
14k 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
93 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
886 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
945 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
254 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
919 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 ...
8
votes
3answers
522 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
817 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
463 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 ...
5
votes
3answers
359 views

Should I follow an open source project's documentation patterns even if they are bad?

I've considered making modules and the like for various languages and other open source things. Where documentation is not specified but rather is communal de facto standard or entirely ad hoc; should ...
9
votes
6answers
478 views

How to use unit tests as a source of information?

A colleague of mine was once at a seminar about agile development, where he heard it is possible to use unit tests as technical documentation. Something like using unit tests as an example of how to ...
0
votes
7answers
223 views

How do you handle / what do you charge for documentation, training, warranty, changes in scope etc… [closed]

I am working with a client right now that wants me to sign a contact with a warranty for a year for no additional charge. As well as any reasonable changes he wants during the contract that are ...
12
votes
4answers
284 views

What exactly comprises 'Documentation'?

When we say 'documentation' for a software product, what does that include and what shouldn't that include? For example, a recent question asked if comments are considered documentation? But there ...
2
votes
1answer
230 views

Alternative to Perl's POD Documentation in Other Languages?

Perl has this really cool documentation method that makes documenting really easy. It's called POD (Plain Old Documentation). Here is an example: =head1 NAME Example::Module - an example =head1 ...
6
votes
1answer
285 views

Does MSDN follow documentation conventions for .NET, and if so is it publicly available?

While browsing the MSDN documentation for the .NET Framework Class Library (FCL) I've always been amazed by how consistent and fully documented it is. It's a constant companion when developing .NET ...
8
votes
2answers
833 views

Documenting a programming language: Reference Manual

We are looking at revamping documentation across our product line. Part of that includes reference manuals for a programming language used as part of the system. When writing a reference manual for a ...
8
votes
3answers
265 views

How do I document necessarily complex code structures?

If I have a piece of code that is mathematically or structurally quite complex and irreducibly so, how would I go about documenting this piece of code? In particular, how can I ensure that someone who ...
10
votes
6answers
758 views

Are comments considered a form of documentation?

When I am writing small scripts for myself, I stack my code high with comments (sometimes I comment more than I code). A lot of people I talk to say that I should be documenting these scripts, even ...
2
votes
8answers
347 views

When and how to commit?

I'm getting used in working with git at the moment. And I'm touching an issue that is unclear to me. I feel compelled, if I think of commiting after a change and making a documenting description. I ...
2
votes
1answer
152 views

Should I provide a language reference in addition to a formal specification for the programming language I am designing?

I am designing a programming language, and I would like to provide a complete documentation for it. So far, I have planned to write the following documents: An initial design outline, mostly as a ...
15
votes
7answers
804 views

How can Scrum be adapted to an academic environment?

I'm currently working with a professor at my university to develop new curricula for the Software Engineering and Capstone Design courses offered in my college. Up until recently, both courses used ...
4
votes
2answers
531 views

Explaining how the code you wrote works [closed]

I was asked to create for a freelance project a Monopoly game in Java. After finishing it the same guy asked me to create four UML diagrams from which he could understand how the game works. ...
5
votes
1answer
134 views

Is there a lightweight method to describe web services, similar to robots.txt or sitemap.xml?

I'd like to provide a very lightweight method to describe my web services. No WSDL, WADL or similar complex stuff. Just a mapping from the web service's base URL to a simple description which can be ...
3
votes
3answers
242 views

How to be productive as an infrequent programmer?

My current day job is mostly project management and client liaison work, but I sometimes get involved in actual coding. I do this either because I have a clear vision of what I want the result to look ...
6
votes
5answers
425 views

Where should a programmer explain the extended logic behind the code?

I have developed a few quantitative libraries in C# where it is important to understand not only the classic information that goes with the XMLDoc comments (which contains basic information with the ...
6
votes
1answer
135 views

How to change documentation expectations from “risk management” to a “project risk”

We are trying to introduce some agile concepts to the business folks but one of our biggest hurdles is their expectations for documentation - the quantity, the authorship/ownership of the documents, ...
6
votes
7answers
546 views

Does not documenting code result in job security? [duplicate]

Possible Duplicate: Should you write good documentation and clean code to increase the “Bus Factor”? I often ask young programmers why they are not documenting their code. Their ...
65
votes
15answers
8k views

I'm going to quit my job because of our platform: how can I leave a productive explanation of this? [closed]

I'm planning on leaving my current job because we're locked into using Blub, with an enterprise Blub framework and a Blub-level web server, on mediocre shared hosting. My coworkers are friendly and my ...