Documentation. The Under Recognised Skill

Question

Documentation. The Under Recognised Skill

David.Poole

SSC Guru

Points: 76035
More actions
April 30, 2021 at 12:00 am

#3870284

Comments posted to this topic are about the item Documentation. The Under Recognised Skill
LinkedIn Profile

Viewing 8 posts - 1 through 7 (of 7 total)

You must be logged in to reply to this topic. Login to reply

Jeff Moden SSC Guru Points: 1004406 More actions · Answer 1

I have found that no matter how easy someone makes things nor how excited people are about proper documentation in say a WIKI or whatever, it almost always fails. With that, I'll say that documentation really belongs in the comments in the code. At least there, it won't get lost.

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)

mfagan12 Default port Points: 1436 More actions · Answer 2

I hate writing documentation but I do it--not only to teach the others who support the software and processes but as I get older, it helps me remember how all of the pieces fit together (I work at a place that does a lot of internal development.)

When I was in college, one of my professors worked for the Department of Defense during the summers as a contractor, and she taught the software engineering courses and she made documentation a large part of it. She was my adviser and recommended that I take a technical writing class, which I did, and I did learn a lot from it. Oddly enough, my "writing cap" comes on whenever I read someone's technical document and note where it's not consistent, headings in a confusing place, etc.

As it is now, I am lucky if I can get my team to not use "texting" lingo in emails, code comments, and message boxes that the end user sees. Sadly, I'm not dealing with young kids but middle-aged men.

Jeff Moden SSC Guru Points: 1004406 More actions · Answer 3

mfagan12 wrote:

Sadly, I'm not dealing with young kids but middle-aged men.

Heh... the one's at the peak of their career... and the Kruger-Dunning curve. 😀

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)

David.Poole SSC Guru Points: 76035 More actions · Answer 4

Sadly Jeff I share your experience

Strangely enough my team have had an internal debate as to where to put documentation. After discussion we came to a few conclusions

If the information is useful across projects then it lives in the organisation's Confluence content
If information is specific to a particular system then it belongs in the systems GitHub repository. Github does have a "Gist" facility that is useful for this purpose.
Where possible use the techniques from Bob Martin's clean code so code comments can be kept to a minimum

The industry in which I work is regulated and one of the items the external auditors pick up on is "where do you store the evidence for key decisions and discussions". With regard to any particular system there will be a decision register kept in GitHub so it lives with the code.

LinkedIn Profile

Jeff Moden SSC Guru Points: 1004406 More actions · Answer 5

David.Poole wrote:

Where possible use the techniques from Bob Martin's clean code so code comments can be kept to a minimum

It's unfortunate that people interpret his book/witings as that. It's kind of like how people have interpreted Knuth's parable about per-optimization and so use DECIMIAL(18,0) and NVARCHAR(256) for virtually everything and are sometimes rather militant about upholding that "principle".

Douglas Adams was almost right. I'll take it one step further and say "Knowledge without understanding is even more dangerous than ignorance".

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)

David.Poole SSC Guru Points: 76035 More actions · Answer 6

Jeff Moden wrote:

David.Poole wrote:
Where possible use the techniques from Bob Martin's clean code so code comments can be kept to a minimum
It's unfortunate that people interpret his book/witings as that. It's kind of like how people have interpreted Knuth's parable about per-optimization and so use DECIMIAL(18,0) and NVARCHAR(256) for virtually everything and are sometimes rather militant about upholding that "principle".
Douglas Adams was almost right. I'll take it one step further and say "Knowledge without understanding is even more dangerous than ignorance".

I don't see how the two are related. I've tried Bob Martin's techniques and they did reduce the amount of commenting ad for that matter the complexity of the code.

LinkedIn Profile

Jeff Moden SSC Guru Points: 1004406 More actions · Answer 7

To be sure, I'm not talking about Bob Martin himself any more than I'm talking about Knuth himself. They are both are spot on.

No... I'm talking about the lot of the folks that have seriously warped what the two have said. I've seen people justify code totally devoid of any comments (for example, all comments are redundant... just read the code) and they (improperly) cite Bob's work as the reason. When I asked a "lead developer" I was working with why he wanted to deploy a table to prod where a half dozen "flag" columns were each DECIMAL(18), he (improperly) cited Knuth's parable as the reason.

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)