DEV Community

Discussion on: Yet another documentation dispute

Collapse
 
bertilmuth profile image
Bertil Muth • Edited

I agree with your general point: dropping all documentation is usually not a good idea. Some documentation is useful. You also provide examples that I can agree to: "a high level overview, and some guidelines, and tips&tricks".

There are some statements in your text that I can't agree to. Like this one: "First of all, an engineer is only a part of a delivery chain. It is really rare that an engineer (or team of engineers) provides a final product. "
Do you think that it is rare that a team of software developers programs, tests, releases and maintains software on their own, given the requirements are known? If that's what you mean, I think you are wrong. I have witnessed many teams who do that successfully.

"Ideas need to be somehow communicated, assumptions must be made and limitations must be discovered. What is the better way to think about them and share our discoveries than writing them down?"
In some cases, a better way may be to talk to the other team members directly.

Related to the bus factor: do code/design reviews, and pair programming. That way, you can reduce "knowledge silos".

Documentation can be useful. But there are other ways of communicating WHAT the code does, including structuring it consistently. So the question is not: should we document or not? But rather: for whom, for what and how much?

Collapse
 
mdabek profile image
Marek Dabek • Edited

Thank you for your comment.
As an engineer I can assure you, that I highly appreciate work being done by fellow engineers :) I agree, that the "delivery chain" part may be unclear.
I see software as a mean of solving some specific set of problems. Software can be a tool (e.g. CAD, trading system), a part of a tool (e.g. infotainment system) or rarely a complete product by it self (e.g. video game). If you think from this perspective, you see that there is more than a team of engineers, first of all there are customers, next, business side of the project, marketing etc. Clear communication between these parties need some sort of common platform and it may be really difficult to gather all of them in single place to give a talk (and probably you would need to prepare slide deck for that - still a documentation;))

Collapse
 
bertilmuth profile image
Bertil Muth

Indeed - informing all relevant stakeholders can be a challenge. Thank you for the answer.