From my experience effective written communication and good comprehension are rare skills. That's the reason meeting culture is so resilient.
High-documentation, low-meeting work culture
391–400 of 524 posts
Re: High-documentation, low-meeting work culture
#392Earlier quoted context omitted.
Having worked with software engineers for the last 10years I can confirm, most don’t like documentation. At least 80% dont
Which is a funny statement as almost all devs like to have documentation.
If I'm simply consuming a library, I find most real-world documentation to be pretty superfluous. A full working example is usually enough to understand how things fit together.
If I'm working on a library, design docs and commented code is nice though.
Re: High-documentation, low-meeting work culture
#393Re: High-documentation, low-meeting work culture
#394Unless entire team is spending 2 days on docs every week, docs are hell. I prefer comments in the code.
Re: High-documentation, low-meeting work culture
#395Earlier quoted context omitted.
I would suggest introducing two things. First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.) Second, I would introduct the idea of a Documentation Portfo…
I'm sure these are great technological answers but this problem can be solved simply and quickly by a human. Not every issue needs to be solved by a butter robot. Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?
> Why not employ a technical writer/documenter/whatever job title you like
Who would supply that person with the information required to write the documentation?
Re: High-documentation, low-meeting work culture
#396My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…
What many dont realize is that documentation is tech debt. You can spend a lot of time and write a lot of documentation and have to also spend time updating it.
I have worked with teams that focus so much time on design docs and insist that everything has to be documented. Pace of work is slow. Documentation and designs became obsolete due to shutting down of services, change in architecture, refactors.
The best form of documentation is code.
Re: High-documentation, low-meeting work culture
#397Moving to America from France, one of my biggest surprises was how poor the average engineer (person really, but engineers affect me directly at work) is at summarizing concepts clearly. I learned a little later that "summary" exercises are not a thing taught in school here, which surprised me. In France, "le résumé" is an exercise that they constantly drill into students (particularly technical ones), in which you t…
In America when we can’t explain something we print more money and redo the solution. Often creating more problems but that’s our flywheel we’re talking about!
Re: High-documentation, low-meeting work culture
#398Earlier quoted context omitted.
> This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow Try explaining that they can't push to the repo because they cloned the http URI and need to generate an RSA token and use SSH instead. Better yet, try to figure out that's the problem when they give you a totally unhelpful version of what the pr…
Or just download Github Desktop onto their machine and show them how to use it.
That's true. They should never be asked to touch the cli on this scenario.
Re: High-documentation, low-meeting work culture
#399Moving to America from France, one of my biggest surprises was how poor the average engineer (person really, but engineers affect me directly at work) is at summarizing concepts clearly. I learned a little later that "summary" exercises are not a thing taught in school here, which surprised me. In France, "le résumé" is an exercise that they constantly drill into students (particularly technical ones), in which you t…
Very interesting perspective! I generally attributed that more to different proficiency levels in English as a second language, rather than language-independent summarization skill, but I guess that's also a realistic option.
Re: High-documentation, low-meeting work culture
#400Low trust, poor communication = low documentation, high meeting.
I work as a consultant with a lot of outsourced teams who poorly communicate or seem to avoid written responsibility.
really like that thought: "low-meeting culture allows us time to do high-value tasks"