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.
2
votes
1answer
137 views
Publishing an internal web app on the internet to a much larger group of users than before
My company has developed a web application based on GWT (Google Web Toolkit) and Ext GWT in the browser, JBoss application server and Oracle in the backend. The app
allows users of different ...
2
votes
1answer
162 views
Would you choose a database or a dvcs as storage for a documentation wiki?
I'm about to start coding a documentation oriented wiki, as a pet project. The core features are:
Extremely easy grouping of documents per version
Markdown syntax (subset of)
Multiple authors ...
11
votes
8answers
2k views
Software to organize and maintain project documentation, specification?
I'm looking for software to organize and maintain projects internal documentation, specification, requirements, etc. Currently we store all documentation as lots of MS Word DOC files in a source ...
0
votes
1answer
180 views
What do I need to include in my OOP design document?
I am a graduate student in aerospace engineering. A lot of my Master's thesis has been on developing an OOP software architecture in MATLAB to facilitate control of Arduino-based vehicles (blimps, ...
1
vote
3answers
559 views
What visualization method would you recommend for event driven programs?
What visualization method would you recommend for event driven programs? Are there industry standard diagrams, such as flowcharts?
1
vote
4answers
285 views
Design Document From Code
I am not much familiar with documenting/System designing stuff.
I have to maintain an application written in C# - working as windows service.
However there is no documentation for this system which ...
0
votes
2answers
152 views
Planning Development Projects
We are currently re-evaluating the way we manage, plan and run our projects (an area that I think we can massively improve upon) so I just wanted to get some ideas as to how other development teams go ...
3
votes
2answers
248 views
How to fix very bad code? [duplicate]
Possible Duplicates:
How do you dive into large code bases?
How do I handle refactoring that takes longer than one sprint?
I have 2 files that cover 5000 lines of code. I have been ask to ...
2
votes
1answer
430 views
What should we include in SSAS cube design documentation?
What should we include in a SSAS cube design documentation?
This is the initial phase of the document. I have included:
data models,
facts,
dimensions,
surrogate keys,
hierarchies and levels ...
6
votes
8answers
424 views
How to manage your functional documentation?
Our functional / business documentation is spread across Word files on our corporate Intranet. It's difficult to find and update information. There has to be a better way. Any ideas?
We had ...
5
votes
3answers
2k views
What is “Problem Domain”
I have to document my program for a school project and we have section called "problem domain" but I have no idea what to discuss in this section.
So the question is: What should be discussed in the ...
48
votes
16answers
3k views
Do TODO comments make sense?
I am working an a fairly big project and got the task to do some translations for it. There were tons of labels that haven't been translated and while I was digging through the code I found this ...
2
votes
1answer
175 views
How do you define, organize, and document your data?
Please feel free to suggest a better name or way of explaining this question - I wasn't quite sure what to call it.
The situation is one that may just come under the heading of "be organized" but I ...
10
votes
6answers
961 views
Self-documenting code vs Javadocs?
Recently I've been working on refactoring parts of the code base I'm currently dealing with - not only to understand it better myself, but also to make it easier for others who are working on the ...
2
votes
5answers
447 views
Why should you document code? [duplicate]
Possible Duplicate:
“Comments are a code smell”
I am a graduate software developer for an insurance company that uses an old COBOL-like language/flat-file record storage system. ...
2
votes
2answers
168 views
Local versioning system especially designed for documents
I have to work on some docs, I need a software that can trace all the modifications that I will make to a specific file or project (group of files): is there something like that?
The important thing ...
8
votes
4answers
444 views
How to document and teach others “optimized beyond recognition” computationally intensive code?
Occasionally there is the 1% of code that is computationally intensive enough that needs the heaviest kind of low-level optimization. Examples are video processing, image processing, and all kinds of ...
5
votes
5answers
176 views
The value of an updated specification
I'm at the tail end of a large project (around 5 months of my time, > 60,000 lines of code) on which I was the only developer. The specification documents for the project were designed well early on, ...
2
votes
1answer
292 views
How do you write straight to the point documentation without looking sloppy and informal?
I'm currently at a contract position and am looking to add to the documentation of the projects I worked on, to assist the next hiree taking over my projects.
The documentation I received was overly ...
5
votes
2answers
103 views
How to document/verify consistent layering?
I have recently moved to the dark side: I am now a CUSTOMER of software development -- mainly websites. With this new role comes new concerns.
As a programmer i know how solid an application ...
2
votes
4answers
297 views
how to layout good documentation
I need to write out a documentation for developers to be able to use some API web software how should i lay out a documentation? What should always be included? And does it need to be really long or ...
2
votes
3answers
340 views
How can I convince my managers to enforce documentation standards?
I'm trying to convince another group in my company— that's about to hand code off to my group—that they need to provide more documentation in their source code, but they're treating it as a "nice to ...
8
votes
5answers
271 views
Should a method comment include both a summary and return description when they're often so similar?
I'm a proponent of properly documented code, and I'm well aware of the possible downsides of it. That is outside of the scope of this question.
I like to follow the rule of adding XML comments for ...
4
votes
3answers
130 views
What could be some pitfalls in introducing a style guide and documentation generating software in a development team?
I'm considering using appledoc, a flavor of Doxygen for use in generating Objective-C code documentation, in order to create documentation for my company's iOS apps. The idea is that a server will ...
2
votes
1answer
222 views
How often do you take notes, and how are you able to maintain a consistent amount?
I take notes about language features, project details, etc. I've noticed that I tend to take a lot of notes when I start learning a new aspect of a language or start working on a new project, but then ...
7
votes
6answers
344 views
Can code be the documentation in open source developer tools? How frequently is it?
It's understandable that after a big development effort, some OSS authors deem reasonable that the project users should make an effort too in order to get started.
Can the source code effectively be ...
2
votes
4answers
157 views
XML or HTML for User Manual/Help and Why?
I want to make User Manual/Help to my program. I found two good ways - XML or HTML - which should I use and why?
I know how to do it in html (I know how to use js, css and such) but in XML it's ...
10
votes
6answers
830 views
Alternativates to HTML Help
We currently use a system called AsciiDoc which allows us to create documentation in a simple text markup. From that we can generate multiple output formats. We only make use of the pdf output and chm ...
5
votes
4answers
1k views
Software testing automation documentation
What document types could be used when describing software testing automation (on any phase, automation planning, test design, implementation, reporting)? Is there any standard types of documents?
If ...
7
votes
3answers
630 views
Is there a Django reference?
I am new to Django. I have found the official topic guides https://docs.djangoproject.com/en/1.3/ an excellent place to learn from. But now I am in a place where I need quick reference to see what ...
4
votes
1answer
203 views
Is there a general pattern that could be used to describe Data Migration?
In our company we have to dismiss a software and introduce a new one. I have received the task to follow and take care of the whole data migration.
We use 3 different data sources (each containing ...
7
votes
4answers
230 views
Should all developers on a team have equal role/responsibility in writing and updating software design documents
I've asked a very similar question few days ago, but because I presented too much of my company's current situation, most answers focused completely on something that I wasn't looking to answer. So I ...
4
votes
7answers
273 views
Recommended ways for getting a good grasp of inherited software
So you've inherited a large codebase that you need to make substantial changes to and you wish to get a pretty complete understanding of the software before starting.
Would you diagram it?
If so, ...
1
vote
2answers
537 views
Is there a difference between property and attribute?
These two words are completely synonymous for me, but I wonder if there's actually a useful semantic difference that I can incorporate into coding/naming conventions/process.
2
votes
1answer
143 views
Can anyone recommend a toolchain-agnostic way of declaring and documenting inter-package build dependencies?
I currently have a project at my hand that I'll leave soon (PhD work) and should be left in an understandable form since it is likely to be taken up, though it is not known yet by whom and when.
...
2
votes
1answer
345 views
what is the meaning of a “Teardown Report”
I am sorry if this a wrong place to ask the question.
I saw the usage "Teardown report" for a product
What does it mean?
1
vote
2answers
373 views
How to draw a (UML) class diagram when the classes are dispersed across a distributed system?
Basically how to denote that class foo is from a different server than class bar ?
44
votes
20answers
3k views
Should you write good documentation and clean code to increase the “Bus Factor”?
One of the main goals of software development companies is to increase their Bus factor This is also advocated in a talk that was organized by Google.
That means that you should code and document ...
1
vote
1answer
97 views
What is the legal status of old reference material? [closed]
I am in the very, very early stages of writing an Amiga 500 emulator, and would like to include the hardware documentation either alongside my source code or in a separate doc package.
As one ...
7
votes
2answers
149 views
Ubiquitous Language - conflict between correctness and usability
A core part of Domain Driven Design is the consistent use of a ubiquitous language across the system - in conversations, code, database schema, UI, tests, etc.
I'm involved in a project in which ...
2
votes
3answers
301 views
Creating public API definition for existing application
Let's say there's a successful open source application (written in PHP if it matters), which provides its users with multiple ways to extend it (think about something like Drupal or Wordpress, lots of ...
1
vote
6answers
217 views
How can I organize my implementation notes to use as a future reference?
How should I document my designing of the app better so that I avoid programming by coincidence? How can I structure notes so that it is clear how an app works so that when I refer to it a year later ...
3
votes
8answers
4k views
Is there a symbol or shorthand for “and is increasing/decreasing”?
This usually happens when I'm writing to developers or other IT professionals.
The context would be something along the lines of ". . . measured at 100 MB/s (and is increasing)."
On paper or a ...
4
votes
3answers
467 views
Writing java doc comments for unit test cases
In my opinion, the unit test cases itself serve as a documentation for the code. My company wants me to write detailed java doc comments on top of unit test cases. Is it necessary to do so? Do you ...
1
vote
5answers
258 views
Source code and project documentation requirements for legal agreement
Question
What kind of documentation and other artifacts would you expect to get in case of taking over existing Java webapp (probably it uses JBoss Seam framework) made in-house?
I would expect to ...
8
votes
8answers
373 views
Moving from one man project to team project in the future. What should I be doing now in preparation and what can wait?
To elaborate I am interested in knowing what people think you need to put in place while still a one man project (team source control, documentation, builds etc) and what things don't need to be done ...
5
votes
5answers
270 views
Whats sort of platform should I host documentation on?
We have a web-based software product that has a growing user-base of around 200+ people.
I won't go into details on our current workflow, but it involves word documents and converting to HTML and I ...
12
votes
7answers
606 views
Should a design document contain a discussion of the pros/cons to a given design or should it focus on facts and rationale?
I'm currently in the process of updating a design document so that it is correct and up-to-date for future developers.
Currently, the document focuses on only the facts, presenting how the design is. ...
8
votes
13answers
562 views
Can you write an unambiguous specification in a natural language like English?
It seems to me that you cannot possibly write a software specification in English that is completely free of ambiguities, simply due to the informal nature of natural language - and therefore that a ...
1
vote
4answers
222 views
What standards does your team use for your specification documents headers and footers?
TL;DR:
What header/footer do you put on your Functional&Technical specifications to avoid people having different versions at meetings?
Story:
We're have a lot of documents, being changed by ...
