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.
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 ...
54
votes
17answers
9k views
What program do you use to write technical documentation?
I'm writing an architecture/technical documentation for an inhouse project and I'm becoming more and more frustrated with Microsoft Word as I seem to use most of my time getting things to align ...
15
votes
6answers
780 views
Methodology for Documenting Existing Code Base
I work as part of a team on an existing application that has no inline documentation, nor does it have technical documentation. As I've been working on various bug reports on the application, I've ...
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 ...
144
votes
29answers
7k views
Humor in Documentation
Is a small amount of lighthearted wording or humor acceptable in source code documentation?
For example, I have an algorithm that has a message hop around a graph (network) until its path forms a ...
46
votes
8answers
6k views
What's the best platform for blogging about coding? [closed]
I'm toying with starting an occasional blog for posting odd bits of coding related stuff (mainly C++, probably).
Are there any platforms which can be recommended as providing exceptionally good ...
11
votes
5answers
3k views
Writing a Software Requirement Specification
I have a few questions about writing a specification and they are:
When we write a software specification, under the topic "User requirements definition" we have to specify the "Functions" and ...
13
votes
5answers
3k views
What does your Technical Documentation look like?
I'm working on a large project and I would like to put together some technical documentation for other members of the team and for new programmers joining the project.
What sort of documentation ...
10
votes
8answers
808 views
How much documentation is enough?
How much technical (for future developers) documentation is enough? Is there a ratio between hours coding and hours documenting that's appropriate?
Papadimoulis argues that you should
produce the ...
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 ...
9
votes
5answers
1k views
Is wiki really appropriate to store document for software development?
Everybody knows that, well-documented software development leads to success. However, it usually means that not only plain text but also binary content will be involved in the document, such as UML ...
7
votes
6answers
862 views
Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?
One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be ...
9
votes
6answers
693 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 ...
5
votes
5answers
326 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 ...
4
votes
4answers
2k views
job handover checklist [duplicate]
I have resigned my old employer to start a new job, and I need to prepare a handover [documentation to be taken by some new employee that haven't arrived yet, and would be some weeks from when I go to ...
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 ...
14
votes
8answers
470 views
What are technical writing principles?
As a programmer, technical writing is an important skill to me. I get a lot of fun from it. I also learned from some good technical articles and books. What I need are technical writing principles or ...
32
votes
18answers
962 views
How can I improve my technical writing?
Writing documentation is part of programming, and writing well
is part of what makes the documentation useful.
So, what are some hints or guidelines for good writing in the
technical realm? What are ...
25
votes
8answers
1k views
Is there such a thing as having too many private functions/methods?
I understand the importance of well documented code. But I also understand the importance of self-documenting code. The easier it is to visually read a particular function, the faster we can move on ...
10
votes
5answers
5k views
Fastest way to document software architecture and design
We are a small team of 5 developers and I'm looking for some great advices about how to document the software architecture and design. I'm going for the sweet spot, where the time invested pays off. I ...
12
votes
2answers
1k 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 ...
11
votes
4answers
1k views
Writing Acceptance test cases
We are integrating a testing process in our SCRUM process. My new role is to write acceptance tests of our web applications in order to automate them later. I have read a lot about how tests cases ...
8
votes
2answers
515 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 ...
7
votes
10answers
2k views
What would be the best way to create documentation?
Well, developers aren't great at writing documentation but we have to. What platform do you use to write it? Microsft Word? Open Office? Latex?
Please note, I'm looking for something that is
(a) ...
6
votes
3answers
773 views
What are the best documentation patterns?
I've seen a lot of different ways to [or not to] comment out the code, specially patterns on desciptions of function details and file purposes.
I'd like to know what is most used pattern to do that ...
10
votes
2answers
683 views
what kind of online technical documentation system would you recommend?
the goal is to have an online documentation system, with these major requirements:
will be mainly used as an intermediate stage for the final technical docs of all our application (which will ...
9
votes
5answers
260 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 - ...
6
votes
4answers
457 views
How to manage an open source project's documentation?
I am the creator of a growing open source project. Currently, I'm becoming frusterated trying to figure out the best way to manage documentation. Here are the options I have considered:
HTML Website
...
17
votes
8answers
844 views
Should you document everything or just most?
It seems a bit of a controversial subject to document everything, including the "JavaBean" syntax of getters and setters for fields: People say its needlessly long and repetitive breaking DRY (don't ...
9
votes
9answers
414 views
Studies on code documentation productivity gains/losses
After much searching, I have failed to answer a basic question pertaining to an assumed known in the software development world:
WHAT IS KNOWN:
Enforcing a strict policy on adequate code ...
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 ...
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 ...
6
votes
9answers
991 views
Setting Up a Development Environment
I am part of an organization that is formalizing their software development processes/capabilities/etc. While the organization is not traditionally a software organization, they want to do this right ...
17
votes
5answers
586 views
How-to convince company to start documenting for legacy software
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 ...
8
votes
4answers
799 views
How can open source projects be successful without documentation about their design or architecture?
I want to improve my programming skills by studying famous open source projects, but I find it is easy to get lost by just jumping into their source code.
So I decided to read their documentation ...
8
votes
7answers
437 views
Commenting/In-Code Documentation Styles
This might be a stupid question, but it's been in the back of my head for a while and I can't find a decent answer anywhere else.
I have a teacher who says we should explicitly list each parameter ...
7
votes
5answers
1k views
Why bother differentiating between functional and nonfunctional requirements?
I understand the difference between the two, but I get questioned by my colleagues of the benefit of labeling requirements as functional or nonfunctional (or transitional). Why bother to do so? He ...
1
vote
7answers
1k views
What is the best offline reference for Python? [closed]
I'm learning Python on a computer with no access to the internet, I have the Python documentation on it but it lacks in several ways (no good introduction to threading, no examples on how to use the ...
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 ...
