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. The types of documentations are: Requirements: Statements that identify attributes, capabilities, ...
5
votes
2answers
226 views
Explaining how the code you wrote works
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
64 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
150 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 ...
4
votes
5answers
222 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
71 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
340 views
Does not documenting code result in job security? [closed]
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 ...
59
votes
15answers
7k 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
133 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
...
51
votes
17answers
3k 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
{
/// ...
5
votes
2answers
90 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
62 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 ...
5
votes
3answers
102 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 ...
9
votes
5answers
284 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 ...
1
vote
3answers
187 views
Generating code documentation
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
440 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 ...
