are your engineers evaluated on the quality and up-to-date-ness of the docs they produced? and are they paid more and promoted faster if they do produce quality docs?
if not, i don't believe you.
High-documentation, low-meeting work culture
351–360 of 524 posts
Re: High-documentation, low-meeting work culture
#352I love the idea of less meetings and more documentation, but I've never seen it work. Here's a few observations...
a. you need a person who "curates" the documentation, otherwise it completely loses organization quickly
b. things become out of date fast and it's not clear if you're reading something out-of-date
c. people write too much, meaning - things turn into this huge long form internal article and people get exhausted in just reading through it. Writing is actually quite hard.
I don't have a better solution/approach to recommend (besides having a curator), but the "less meetings / more documentation" train always seemed oversold to what I've experienced first hand.
Re: High-documentation, low-meeting work culture
#353Earlier quoted context omitted.
> A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. A ticket represents a process (otherwise it has no added value over git commit message) and thus creates much more work than a couple of seconds.
> A ticket represents a process Yep, and that process also involves other people, to review/ approve the fix to the typo. It then goes from being a few seconds of elapsed time and actual time (to just commit a fix to the typo) to taking hours, days or weeks of elapsed time and hours of actual time and forcing context switching on, and interrupting the workflow of, all of people involved.
Yes, handoffs have overhead and create process waste. They are a process smell and should be investigated for ROI.
Re: High-documentation, low-meeting work culture
#354Earlier quoted context omitted.
I work in medical devices so we have to write a lot of docs. But they all disappear in document management systems where you can't find anything if you don't already know where it is. Are there no document management systems that are actually useful?
A good secretary (or a bunch of them) and filing cabinets. You may still not know how to find anything, but they will. Like a lot of other things, this has suffered from computerization making it yet another small part of everyone's job (which also increases context switching, the amount of shit you need to know and keep track of, and generally makes jobs more stressful) rather than a specialty that's the main focus…
"Like a lot of other things, this has suffered from computerization making it yet another small part of everyone's job (which also increases context switching, the amount of shit you need to know and keep track of, and generally makes jobs more stressful) rather than a specialty that's the main focus of a few workers."
Nicely said. I am getting really stressed out how complex things are becoming. It's already hard to keep up with git, Jira, Bitbucket, AWS, k8s, Helm, JS frameworks, databases and whatsoever. But then add hard to use document management systems and f...ed up processes that are mainly designed for management to get nice reports and not for productivity. Now you are a bad developer and you are a bad document management person because it's simply impossible to be good at all this stuff.
I am constantly preaching to management that we need specialized tech writers and specialized devs that are good at their respective. But I guess it looks cheaper to waste time and energy of engineers on stuff they aren't good at.
Re: High-documentation, low-meeting work culture
#355My 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…
There are docs and then there are Docs. I think documents should be treated as source code. Go through a proper PR process so that you know what the latest and greatest is. Maintaining a wiki is one of the worst ways to document. It just creates a sprawl that is hard to control. I deal with it on a daily basis but have had little success with getting my team moving to our source control system for documents.
[deleted]
Re: High-documentation, low-meeting work culture
#356Earlier quoted context omitted.
> Why not employ a technical writer/documenter/whatever job title you like Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the quest…
You explained why no one wants to take the job in the typical company. They would be disrespected, and likely soon fired. But a different question is, why is no company trying to do this differently? Like, hiring one good tech writer to maintain the company documentation, and paying them as much as they pay the developers.
As a tech writer, I think this is because it's hard to concretely quantify the value that a tech writer brings, and thus it's hard to make a clear business case for.
Re: High-documentation, low-meeting work culture
#357Earlier 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?
I’ve advocated for hiring a librarian but I haven’t ever been able to make the case successfully. So yes, I agree with you, but the “how” of structuring and the “who” are orthogonal.
This is about prioritizing the documentation you write.
Re: High-documentation, low-meeting work culture
#358Earlier quoted context omitted.
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?
My experience is that for internal documentation the time spent explaining things to a technical writer is bigger than the time spent writing the documentation This isn’t the case for external documentation, that has to be more polished, needs sign offs and images and demos and stuff - tech writers can come in useful here
It may take more time to explain it to a tech writer than it would for you to write it, but in most cases the final docs written by a tech writer will be much better.
Re: High-documentation, low-meeting work culture
#359Earlier quoted context omitted.
git works for us across business/electronics/electrical/mechanical/software. The exception is daily supply chain and accounting, which due to factors like urgency, multiple stakeholders per order, high pace of handover, external system integration, multilingual presentation requirements and nontechnical users we prefer a dedicated web based system with more of a real time focus with event hooks (eg. notification, tra…
What kind of docs do you have in git? Git doesn’t work well with binary file formats like Word, Excel or Visio. You can do it but the diff won’t work.
Markdown + .webp, mostly. Some 'TeX.
Re: High-documentation, low-meeting work culture
#360I've worked at high-documentation companies and low-documentation companies.
Documentation is hard to create and hard to maintain. It is essentially a simulation of an underlying reality, and that underlying reality *always* changes faster than the documentation can. So the documentation ends up being spotty, except for the parts that you find a way to automate. It's hard to automate all documentation, since so much knowledge is trapped in the analog world, and in peoples' minds.
Companies like storytell.ai are trying to solve the problem of creating documentation and written artifacts automatically out of Zoom recordings, etc. Others, like WeRice, are trying to create it out of videos of maintenance work done on equipment in the wild. I respect both efforts a lot. It's a hard problem to tackle.