Documentation. The Under Recognised Skill

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

  • 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".
    "Dear Lord... I'm a DBA so please give me patience because, if you give me strength, I'm going to need bail money too!"

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

  • 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.

  • 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".
    "Dear Lord... I'm a DBA so please give me patience because, if you give me strength, I'm going to need bail money too!"

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

  • 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.

     

  • 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".
    "Dear Lord... I'm a DBA so please give me patience because, if you give me strength, I'm going to need bail money too!"

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

  • 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.

  • 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".
    "Dear Lord... I'm a DBA so please give me patience because, if you give me strength, I'm going to need bail money too!"

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

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

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