Skip to Content
avatar image

[Status update] Is there such a thing as "too much documentation"?

I'm at it again with my IDM docu and wonder, if I should include the content of my email constants, too, and not just their (technical) names and use cases. Hmmm...

* Please Login or Register to Comment on or Follow discussions.

17 Comments

  • Feb 07, 2017 at 06:18 PM

    In my opinion, no. With the exception of furniture/toys that need to be assembled, I've never complained about a product being over documented :)

    • Feb 07, 2017 at 10:15 PM
      CONSTANT c_a TYPE c VALUE 'A'.    "Constant with value A
      CONSTANT c_b TYPE c VALUE 'B'.    "Constant with value B
      CONSTANT c_c TYPE c VALUE 'C'.    "Constant with value C
      CONSTANT c_d TYPE c VALUE 'D'.    "Constant with value D
      CONSTANT c_e TYPE c VALUE 'E'.    "Constant with value E
      ....

      Not kidding... I have seen this.

      • Feb 07, 2017 at 10:49 PM

        Oh boy! :D

        But I remember this as an example for not so great code documentation via comments.

  • Feb 07, 2017 at 07:27 PM

    Add them - you can't know for sure who will be the next person reading the documentation...

  • Feb 07, 2017 at 07:41 PM

    If there is then I'd certainly prefer it over "too little". Just a few months ago we received a specification for an interface that had (I'm not making this up) "contact Steve or Lucy if you have questions". To this day I have no idea who those luminaries are.

  • Feb 07, 2017 at 10:52 PM

    I'm a big fan of detailed documentation, so I guess I'll add them. And the scripts I use in the workflows, too.

    I'm trying to complete my request documentation, but now I'm thinking about more and more stuff to write down about it. Looks like I'm a step further away from completing it instead of getting to the finish line. ^^

    Also I stumbled about some old stuff today during this that I could delete, because it's not in use anymore (constants mostly), so doing documentation helps in that regards, too, because you're checking so much. :)

    • Feb 08, 2017 at 02:03 PM

      Just write "contact Steffi if you have questions" and you're done. :)

      • Feb 08, 2017 at 02:07 PM

        My contact info is in there, too, under "Responsible persons". ^^

  • Feb 08, 2017 at 07:45 AM

    Document! Document!

    If well done, a detailed documentation helps alot in maintainence.

    i always produce mine own and never regret about it, despite i hate doing it.

    • Feb 08, 2017 at 08:00 AM

      I always liked writing documentation. But I was always lucky enough that nobody tried to interfere in how I write it.

      • Feb 08, 2017 at 08:59 AM

        Written documenation? Isn't that sooo old school?

        Think of different media, say a clever video with you and one collegue talking about why you decided to do some things exactly that way and why alternatives were dismissed, just hold your handwritten notes into the camera, make some jokes (which will be easy, right?)...

        That will be fun for anyone in need of documentation later (well, in case the codec does still work), and probably embarrasing for oneself, but...

        ...now I'll stop dreaming.

        ---------

        Disclaimer: I write documentation, too, but now and then I think the mentioned way would be really handy to explain certain decisions and functions to users (which usually won't read longer documents at all, as everyone might have experienced)...

        • Feb 08, 2017 at 09:19 AM

          That's why I include nifty workflow pictures created with Visio, so it's not just text, text, text. ;)

          Doing videos is more for training material IMO, not for documentation purposes. Who could follow me rambling on about the technical names of attributes, constants and tasks. I think this is stuff that needs to be in text form.

          Describing how something works on the other hand could probably be done also through video. If you're good at explaining things.

          • Feb 08, 2017 at 10:24 AM

            Sorry, as usually I forgot to mark my contribution as (primarily) ironically meant...:)

            And yes, I hate to make that clear lateron, possibly something to add to the "I really hate it when" discussion:)

          • Feb 08, 2017 at 02:37 PM

            i suck in drawing WF in Visio.

            I prefer to make clear bulleted list, with all the links i need.

  • Add comment
    10|10000 characters needed characters exceeded