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

3
votes
3answers
912 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 ...
8
votes
4answers
20k 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
111 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
1k 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 ...
4
votes
2answers
312 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
623 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
979 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
493 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
371 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 ...
8
votes
6answers
570 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
227 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
301 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
268 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
296 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
1k 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
301 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
813 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 ...
3
votes
8answers
364 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
160 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
1k 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
785 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
145 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
264 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
554 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
149 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
636 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 ...
63
votes
15answers
9k 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 ...
2
votes
5answers
167 views

What is a generic term for name/identifier? (as opposed to label)

I need to refer to a number of things that have both an identifier value (used in code and configuration), and a human-readable label. These things include: database columns dropdown items ...
54
votes
17answers
4k views

How to deal with tautology in comments?

Sometimes I find myself in situations when the part of code that I am writing is (or seems to be) so self-evident that its name would be basically repeated as a comment: class Example { /// ...
6
votes
2answers
230 views

How do you track existing requirements over time?

I'm a software engineer working on a complex, ongoing website. It has a lot of moving parts and a small team of UI designers and business folks adding new features and tweaking old ones. Over the last ...
0
votes
1answer
735 views

How to structure process description documentation?

I'm writing a document describing process improvement recommendations. I have some best practices I've learned so far. I use those practices most of the time. But I suppose there are other ways to ...
6
votes
2answers
143 views

How to keep user's guide in lockstep with branches for a non-developer?

Our current user's guide is built using asciidoc. The documentation is managed by a non-technical person, but we keep the source text files as well as generated HTML in source control. Issues arise ...
10
votes
5answers
3k views

Is it a good idea to write requirements specifications by stories?

We're using agile methods in my current project at the moment, and we have heaps of stories like these: As an assistant, I want to pay a customer a refund so that they can get some money when they ...
3
votes
3answers
1k views

Generating code documentation [closed]

I want to generate code documentation in a simple format. The key items are Method Signature, members, constructors, methods. I am taking various applications in .NET and creating documentation for ...
10
votes
7answers
851 views

How can I document someone else's past work?

We're in a bad situation of having very little documentation on customization our past workers made to a business critical system. Lots of changes were done to Crystal Reports, database entities, and ...
9
votes
4answers
2k views

Prepare source code handover plan

Our company is about to acquire a source code of a huge product. What are thing to take into consideration when the handover starts, to make sure we have everything and be capable to maintain that ...
8
votes
6answers
2k views

What is a good non-technical example of a cumulative error?

I'm working on a report which needs to explain in non-technical terms the effects of a cumulative error, and why it is of importance to use absolute calculations. Definition of 'cumulative error' ...
3
votes
3answers
8k views

Are High Level Design and Low Level Design documents needed to follow Agile development process?

Our team is developing a project using an Agile development process. All of our requirements are converted into product backlog items and task are broken down based on that. One of my team member ...
4
votes
3answers
593 views

Documenting and enforcing programming standards and guidelines for shared library

Myself and another developer with the go ahead from our IT director have started a general purpose library in .NET with the intention that it will provide many common purpose classes that we use in ...
5
votes
6answers
584 views

Should I add MSDN notes or Stack Overflow links to source code? [duplicate]

Possible Duplicate: Is it OK to put a link to Q&A sites in a program's comments? I'm creating a powershell / C# host and want to add the following comment // This method cannot be ...
2
votes
3answers
778 views

Ways to present testing results

I'm doing a school project which requires us to create a computer application and then write documentation; therefore I have to write testing documentation, I already have a of test plan (Validate all ...
6
votes
5answers
372 views

How should I choose the right documentation for my team?

I've asked this question a few days ago about how much documentation should be made and now I realize I may have been asking only half of the question. My goal is to promote some sort of ...
9
votes
5answers
358 views

Determining the right amount of documentation

Where I currently work the general approach is - avoid documentation as much as possible Only document if a different team will need it just for clarification, I don't mean code-documentation - ...
21
votes
5answers
1k views

How-to convince company to start documenting for legacy software [duplicate]

It has been less than a year since I joined my current company. Their majority of sales have come from a single product that has been alive since the last 10 years. However, there is minimal (if at ...
0
votes
3answers
1k views

How do I write a specification? [duplicate]

Possible Duplicate: how do I write a functional specification quickly and efficiently With so many projects changing halfway - and clients assuming much can be changed at no additional cost ...
11
votes
1answer
306 views

Is iterative documentation development possible, and does it deliver effective documentation?

I have a project for university which I won't be starting immediately, but have been thinking about for a reasonably long amoung of time. I understand that University project development isn't like ...
7
votes
2answers
685 views

DRY way to write Javadoc on overload methods

I want to write Javadoc in DRY way. But the oracle document about Javadoc says write same thing again in overload method comment. Can't I avoid repetition?