Skip to Content

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

1
Show 17
* Please Login or Register to Comment on or Follow discussions.
avatar image
Feb 07, 2017 at 05:31 PM edited Feb 07, 2017 at 05:32 PM
111

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 :)

1 Share
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.

1 Share

Oh boy! :D

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

0 Share

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

0 Share

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.

3 Share

Steve & Lucy :-)

stevelucy.jpg (118.3 kB)
2 Share

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. :)

0 Share

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

2 Share

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

0 Share

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.

0 Share

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

0 Share

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

1 Share

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.

1 Share

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:)

0 Share

Oh, I understood that you meant it more like a joke. ;) Nontheless, I thought about a use case.

0 Share
Show more comments

i suck in drawing WF in Visio.

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

0 Share
10 |10000 characters needed characters left characters exceeded