DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

Itai Katz
Itai Katz

Posted on

What's worse: Stale documentation or no documentation?

Stale documentation. 1000%.

Agree?

Top comments (37)

Collapse
mcsee profile image
Maxi Contieri

Documantation is always obsolete

Write good tests instead
Documentation lie, Tests can't lie
Documentation is dead, tests are alive

Collapse
joelbonetr profile image
JoelBonetR

I also find tests necessary but tests and doc cover two different things.

Documentation is to provide ease to use for developers while tests "explain" behaviour. You also can add documentation inside your tests and point to the issue or whatever.

On the other hand, there are ways (linter, CR) to ensure both that people add doc plus that they update the doc along changes in functions/methods.

If we're talking about a different kind of documentation (wiki) then yes, this -almost- never ends well.

Collapse
mcsee profile image
Maxi Contieri

In My code reviews, I usually remove Doc documentation since they bring no value and are in danger of obsolence. No documentation is better than useless documentation

see

and

Thread Thread
joelbonetr profile image
JoelBonetR

So instead enforcing the documentation and keeping it up to date you prefer to remove it... What can go wrong.

It may not bring "value" but it speeds up future developments and maintenance for sure πŸ€·πŸ»β€β™€οΈ

Thread Thread
mcsee profile image
Maxi Contieri

ussually I just don't remove it. I write a self documenting test instead.
Then I remove th comment before it gets obsolete

Maintenance is granted as long as you have automated tests.
You can add a bunch of documentation and yet bring zero maintenance value since developers don't read documentation. But if they break a test, they will have inmediate feedback

Thread Thread
joelbonetr profile image
JoelBonetR • Edited on

Well, it depends on the environment/language till certain point but as I already said, documentation can be enforced through lints or any other tool and you'll get feedback for sure.
check this as example.

On the other side, tests should not don't apply to every single function you have. Tests are meant to ensure behaviour (public interface) while documentation in functions is meant to add information to the implementation details.

That's the reason I said both are not exclusive neither they are replaceable between each other.

Thread Thread
mcsee profile image
Maxi Contieri

I see your point in your article.
If it keeps updated automatically I am ok with it.

Implementation details are accidental and can change as long as no external contract is broken.
documentation should be the exception for a very small use cases, IMHO

Collapse
qm3ster profile image
Mihail Malo

That's where doctests come in.

Thread Thread
mcsee profile image
Maxi Contieri

What is their added value?

Thread Thread
joelbonetr profile image
JoelBonetR

What do you understand as "value"?

Thread Thread
mcsee profile image
Maxi Contieri

The add value that doctests add

If I see a point I will start to use them instead of removing them

Thread Thread
qm3ster profile image
Mihail Malo

Usage examples that never go stale because they are tests that run.

Collapse
taijidude profile image
taijidude

I strongly disagree. Unit Tests are a good source of additional documentation but should not be the only one.

Collapse
mcsee profile image
Maxi Contieri

In which other way would you add functional documentation?

Thread Thread
taijidude profile image
taijidude

Good question. One thing that comes to mind is diagrams. Granted not perfect, but a good diagram can be okay to maintain and offer clearity. Even better if i can generate it from my Code. But i know the answer is vague.

Thread Thread
mcsee profile image
Maxi Contieri

IMHO, Diagrams are for human to human comunication

Used to document sofware is yet another code smell

Thread Thread
mcsee profile image
Maxi Contieri

you can add functional tests, contract testing, integration testing, cucumber, BEHAT and so on

All of them are alive and kicking. documentation is dead prose

Thread Thread
taijidude profile image
taijidude

Again, disagree but i see your point. Having diagrams doesn't make it automatically good. The main thing that documentation has to do is communicate your ideas, design information to other humans. I'm a visual guy. When i want to understand something or discuss with colleagues i start drawing.

Thread Thread
mcsee profile image
Maxi Contieri

I'd love to discuss with you using diagrams since we are both humans

Thread Thread
taijidude profile image
taijidude

Okay, my pleasure. ☺️

Collapse
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ • Edited on

Nice false dichotomy that you have there

In real life, if I don't understand your readme, or can't follow your first tutorial, I'm not gonna read your unit tests.

Collapse
mcsee profile image
Maxi Contieri

That's ok to me.
I don't use code without coverage because I don't know how or if it works.
I will upload a new github repo documenting how to break RSA and to prove P=NP since I can document anything.

I think we can both be safe as long as our roads don't cross.

Thread Thread
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄

Just to be clear, your answer to "A xor B is a false dichotomy" is "B without A doesn't work"?

Collapse
theaccordance profile image
Joe Mainwaring

No Documentation is worse IMO, but I do think there some stale examples in the wild that are so egregious, it would be better if people didn’t stumble upon those docs.

Stale docs are annoying but if the documentation has a contributor workflow, then they can be quickly updated. No docs require more work to correct.

Collapse
bertilmuth profile image
Bertil Muth

If the differences between the documentation and reality are minor, stale documentation may still help. But that’s often not the case, so then it’s misleading and you’re maybe better of with no documentation at all.

Where possible, I prefer Living Documentation directly connected to automated tests, or generated from production code.

Collapse
ccoveille profile image
Christophe Colombier

Have a documentation with 2 articles about the same thing. And each of them make you think a part of it is right, but your have to go deep dive the code. To understand it's even worst that you think.

Here I'm talking by experience.

Collapse
frankfont profile image
Frank Font

Depends on what kind of stale.

  • Stale as in missing information, incomplete, but accurate for what little it does describe? Great! --- I want more but I'll take what is there.

  • Stale as in wrong? Nobody wants that!

Collapse
alidarrudi profile image
ali

In my opinion, having no documentation is much worse than having outdated documentation. It is possible to extract a point from the old document, but without the document it will be very difficult. However, sometimes old documents are also misleading. Especially if they are not updated. But it is better than having no documents.

Collapse
ccoveille profile image
Christophe Colombier

I depend on what is the documenation about.

If it's about code, then I prefer to have nothing, but also the time needed to understand the code, code is almost always self explanatory.

But then, if you have nothing and what were looking for is about either:

  • the reason why we made some choices.
  • the functionals of what the code is trying to achieve
  • a deal almost forgotten by team, that still bring money to the company.
  • etc ...

Think about a service that make external calls to a black box. Or a client that calls an old APIs you have. Having a contact name is priceless.

In such cases, I always prefer to have a walking dead documentation than nothing, because the code cannot help me.

Collapse
taijidude profile image
taijidude

No documentation. With stale documentation i have at least clues where to look.

Collapse
clavinjune profile image
Clavin June

stale documentation because it gives wrong expectations

Collapse
javascriptstefan profile image
JavaScriptStefan

Both

Collapse
guithomas profile image
Guilherme Thomas

I'll go with stale documentation. If you try to understand from zero its still better than understand it wrong.

Collapse
gamerseo profile image
Gamerseo

I don't know what's worse. Ideally, the site is up-to-date in all respects.

Collapse
qm3ster profile image
Mihail Malo

Worse is when my tummy hurts

Collapse
patricktingen profile image
Patrick Tingen

Defensively, with no docs, at least you know exactly what you have

Collapse
drsensor profile image
Fahmi Akbar Wildana

Show don't tell

Working examples are always better than explanation. If you're too lazy to write a test case, example code can act as a smoke test too.

🌚 Life is too short to browse without dark mode