How do you know what’s it supposed to do, if no one actually wrote that down, other than
As a person.
I would like it to work
So i can do the things.
To be fair, at least that’s something…
Or maybe for testing the documentation is the code. The code does this, write a test that accepts it does this.
I like the concept of describing things in scenarios and having data objects embedded in the scenarios. I think gherkin if a bit too restrictive, the same way user stories are, but a more natural verbose scenario that was parameterised with variables tied to actual data makes it explicit what is supposed to happen and what data the system will consume, create or manipulate.
E: there is of course other types of documentation available
For those of us who read developer code better than PO/PM “english”, indeed code is the documentation, or at least can be. Ofc when the code is thousands of lines long, split between multiple files, interacts with networked resources that you’ve never heard of, sending signals that do who knows what downstream, upstream, sidestream, flipstream, or whatever… yeah documentation can be important too:-). Also when the code is in some other language that you don’t know quite as well.
By “testing” I should clarify that I did not necessarily mean things like user or unit testing - though that stuff has its place too - but rather even more foundational “verify that your code does what it is supposed to do” kind of testing:-). One could argue that that is just straight-up “writing code”, but then too writing documentation could be folded into that as well, e.g. having things like human-readable variable names, Pre & Post conditionals for functions and the like, so it all gets a bit fuzzy here.
And if we are being pedantic, a “quick call?” could save a month or year’s worth of time “writing code”, to ensure that you know what needs / desires to be done. Likewise, updating Jira could save someone else SOO much time, or even yourself down the line when you wonder about something that was never mentioned. So I assume that OP was not taking this all that seriously, and just joking about “yeah, meetings are less fun than writing code”, and we all ofc have to pile on with our further opinions about what’s fun:-).
Bonus: good tests can also serve as technical documentation.
Though I have to disagree with the notion that documentation is as important or more so than code.
Documentation is certainly near the top of the list and often undervalued. I’ve worked on a project where documentation was lacking and it was painful to say the least.
Without documentation, changing or adding features can be a nightmare. Investigating bugs and offering support is also very difficult. But without code, you have nothing. No product, no users, no value.
There are (inferior) substitutes for documentation: specialized team knowledge, general technical expertise. These alternative pools of knowledge can be leveraged to create and improve documentation incrementally.
There’s no replacement for the actual functionality of your applications.
And isn’t testing even more so!?
How do you know what’s it supposed to do, if no one actually wrote that down, other than
As a person.
I would like it to work
So i can do the things.
To be fair, at least that’s something…
Or maybe for testing the documentation is the code. The code does this, write a test that accepts it does this.
I like the concept of describing things in scenarios and having data objects embedded in the scenarios. I think gherkin if a bit too restrictive, the same way user stories are, but a more natural verbose scenario that was parameterised with variables tied to actual data makes it explicit what is supposed to happen and what data the system will consume, create or manipulate.
E: there is of course other types of documentation available
For those of us who read developer code better than PO/PM “english”, indeed code is the documentation, or at least can be. Ofc when the code is thousands of lines long, split between multiple files, interacts with networked resources that you’ve never heard of, sending signals that do who knows what downstream, upstream, sidestream, flipstream, or whatever… yeah documentation can be important too:-). Also when the code is in some other language that you don’t know quite as well.
By “testing” I should clarify that I did not necessarily mean things like user or unit testing - though that stuff has its place too - but rather even more foundational “verify that your code does what it is supposed to do” kind of testing:-). One could argue that that is just straight-up “writing code”, but then too writing documentation could be folded into that as well, e.g. having things like human-readable variable names, Pre & Post conditionals for functions and the like, so it all gets a bit fuzzy here.
And if we are being pedantic, a “quick call?” could save a month or year’s worth of time “writing code”, to ensure that you know what needs / desires to be done. Likewise, updating Jira could save someone else SOO much time, or even yourself down the line when you wonder about something that was never mentioned. So I assume that OP was not taking this all that seriously, and just joking about “yeah, meetings are less fun than writing code”, and we all ofc have to pile on with our further opinions about what’s fun:-).
Agree, I would put tests higher than documentation, I just got to documentation first and was triggered enough to comment immediately
Hehe, no hate here - I likewise was spinning off of what you said, carrying it forward:-) (bc those are quite important matters indeed!)
Bonus: good tests can also serve as technical documentation.
Though I have to disagree with the notion that documentation is as important or more so than code.
Documentation is certainly near the top of the list and often undervalued. I’ve worked on a project where documentation was lacking and it was painful to say the least.
Without documentation, changing or adding features can be a nightmare. Investigating bugs and offering support is also very difficult. But without code, you have nothing. No product, no users, no value.
There are (inferior) substitutes for documentation: specialized team knowledge, general technical expertise. These alternative pools of knowledge can be leveraged to create and improve documentation incrementally.
There’s no replacement for the actual functionality of your applications.