3 ms·

I honestly believe documentation is more important than tests in some cases. The time spent by a dev every time to understand why a method was created that way

by onel 2y ago

I honestly believe documentation is more important than tests in some cases. The time spent by a dev every time to understand why a method was created that way adds up quickly. The what is more evident from the code. The idea of writing documentation before the code is interesting, it's thinking out loud

kmerroll 2y ago
Wholeheartedly agree, however... It's well accepted that most developers would rather chew off their own arms than write documentation. The acceptance, sort of, of TDD shows that developers would rather code even in pseudo code test languages than write narrative prose.
- datavirtue 2y ago
  I write a "functional description" that describes the functionality of each screen from a user's perspective. It also contains technical details to jumpstart devs but the main focus is on describing how the software works. Oddly enough, I write these in Word and keep them on SharePoint. This allows the team to add comments, maintaining the historic discussion around certain functionality.
deleted 2y ago
[deleted]
bunderbunder 2y ago
"During the early phase of software development the documentation is the specification and is the design... If the documentation is bad the design is bad. If the documentation does not yet exist there is as yet no design, only people thinking and talking about the design which is of some value, but not much." "During the testing phase, with good documentation the manager can concentrate personnel on the mistakes in the program. Without good documentation every mistake, large or small, is analyzed by one [person] who probably made the mistake in the first place because [they are] the only [person] who understands the program area." "Following initial operations, when system improvements are in order, good documentation permits effective redesign, updating, and retrofitting in the field. If documentation does not exist, generally the entire existing framework of operating software must be junked, even for relatively modest changes." All quotes from "Managing the Development of Large Software Systems" by Winston Royce, 1970. All quotes perfectly match my experience working on projects that were developed using contemporary low-documentation agile development methods.

by onel 2y ago

kmerroll 2y ago

Wholeheartedly agree, however... It's well accepted that most developers would rather chew off their own arms than write documentation. The acceptance, sort of, of TDD shows that developers would rather code even in pseudo code test languages than write narrative prose.

datavirtue 2y ago
I write a "functional description" that describes the functionality of each screen from a user's perspective. It also contains technical details to jumpstart devs but the main focus is on describing how the software works. Oddly enough, I write these in Word and keep them on SharePoint. This allows the team to add comments, maintaining the historic discussion around certain functionality.

deleted 2y ago

[deleted]

bunderbunder 2y ago

"During the early phase of software development the documentation is the specification and is the design... If the documentation is bad the design is bad. If the documentation does not yet exist there is as yet no design, only people thinking and talking about the design which is of some value, but not much." "During the testing phase, with good documentation the manager can concentrate personnel on the mistakes in the program. Without good documentation every mistake, large or small, is analyzed by one [person] who probably made the mistake in the first place because [they are] the only [person] who understands the program area." "Following initial operations, when system improvements are in order, good documentation permits effective redesign, updating, and retrofitting in the field. If documentation does not exist, generally the entire existing framework of operating software must be junked, even for relatively modest changes." All quotes from "Managing the Development of Large Software Systems" by Winston Royce, 1970. All quotes perfectly match my experience working on projects that were developed using contemporary low-documentation agile development methods.