Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

High-documentation, low-meeting work culture

tremendous.com

Post reply on HN
Print view View original

311–320 of 524 posts

Re: High-documentation, low-meeting work culture

#311

Post by TylerE »

BurningFrog wrote: post #298
canucklady wrote: post #20

My 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…

Everyone wants accurate updated documentation. Nobody knows how to accomplish this. Whatever the solution is, if one exists, I'm sure it involves a lot of work keeping documentation up to date.

They know how (documentation is embedded in/generated from code) they just don’t want to.

Out of date doc is worse than no doc, because it makes you feel all warm and fuzzy right until you footgun.

Re: High-documentation, low-meeting work culture

#312

Post by dougk16 »

canucklady wrote: post #20

My 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…

One solution to this is to become an oracle at your company. Any time someone (namely someone higher in the company who is responsible for your pay) has a question, no matter how many times it's been asked, how recently it's been asked, how obvious and repeated it is in the documentation, you answer quickly and thoroughly, like a machine. After a year or two of this, you'll be able to ask for any raise, or to work remote, or to even switch to contracting. They won't want to lose you.

Re: High-documentation, low-meeting work culture

#313

Post by matai_kolila »

mr_gibbins wrote: post #128
ebiester wrote: post #30

Earlier 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?

Er, the butter robot joke was a throwaway line about the exential crisis of a robot that carries butter, not a blueprint or metaphor about how to conduct software development, please for all that is holy don't try to read more into that than is there...

Re: High-documentation, low-meeting work culture

#314

Post by mehh »

rcarr wrote: post #134

I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departme…

Ha yeah good luck with that, many people think confluence is too technical to use!

Re: High-documentation, low-meeting work culture

#315

Post by lukewiwa »

origin_path wrote: post #132
cmdrriker wrote: post #119

Earlier quoted context omitted.

Does it matter what tool you use to write documentation? Confluence gets a lot of sh*t because its in the grown-up camp of tools but I know people who've got problems even with nano. It's incumbent upon all users or members of the team to use the common tool along with agreed upon standards. Otherwise even if you wrote documentation in your own hemoglobin, no one would touch it either. Some manager prob chose _______…

It does matter because the issue with wikis (not just confluence) is there's no approval or review workflow. Imagine trying to write a large program in which everyone could just commit at will, with no review process whatsoever, and where nobody had made any decisions about design up front. There'd be duplication, dead code, the organization would be crazy. That's the average wiki. It's a commons and a tragic one. To…

The last thing I want is to raise the friction for writing down documentation.

It's hard enough to get technical minded people to contribute to a git (or style) based knowledge base.

Pick your poison I guess but I'm quite happy to have testers/BAs/directors/etc able to quickly jot down thoughts roughly than have it disappear into the ether.

Re: High-documentation, low-meeting work culture

#316

Post by beckingz »

CrypticShift wrote: post #292
ericmay wrote: post #135

Earlier 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…

Summary: HIGH Documentation = HIGH staleness + HIGH loss. HIGH staleness is because nobody wants to do it (status is lower). Also… nobody else can do it (full understanding of what is being documented is needed) So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopel…

AI can't solve search. If you look at how google did it, they bullied and cajoled site owners to add detailed metadata to the top of pages. It's not magic, it's creating incentives for people to create documentation.

Re: High-documentation, low-meeting work culture

#317

Post by ozim »

hinkley wrote: post #91
tqi wrote: post #12

Sounds like this works great for them, and an awesome environment to be a part of. However I'd be very curious to see how this evolves as the company grows. Personally, I am skeptical that this is sustainable in the long term. In my experience, most people are a) bad at writing and b) hate reading. And as a company grows, and the number of documents that need to be written and read explodes, this work pattern eventua…

People hate reading bad writing. As someone who dabbled in creative writing before discovering my vocation, I see a lot of problems caused by people not bothering to explain themselves clearly. As my time in the industry grew I begin to see people who were confused about their own ideas and came to see how many things we don’t even explain to ourselves. Which likely plays a role in how defensive people get about some…

I got to the point where I sign up to "people hate reading full stop".

It is not to blame anyone, because what people want in reality is answers and answers now - not searching through 20 pages of text, even if it is well written.

My tasks at work are not "read Anna Karenina and think about it". They are more "given X, Y and Z can you produce G and if yes, do so ASAP please".

Which takes us to the meetings and asking around which quite often is quickest way to get correct answer - even if answer is in a "well written down documentation".

Simple text search is not there yet, any advanced system for "knowledge management" fails really quickly in that regard because it takes effort to learn. It is either that setting up such knowledge management system takes too much time or getting used to it takes too much time.

This is why I cringe when I see knowledge management systems posted here on HN, usually these are cute toys but are not really solving anything unless their founders convince 90% of world population to meticulously fill in data in such system.

Re: High-documentation, low-meeting work culture

#318

Post by sib »

crazygringo wrote: post #283
sdflhasjd wrote: post #129

Earlier quoted context omitted.

What I find is that it's very "dumb", almost "... WHERE filename LIKE '%query%'" dumb. Example might be searching for " Technical Spec". - Can't find "Technical Specification" in the " " folder. - Can't find "Tech Spec" (and vice versa) - Can't find " " Is there some "enable real search functionality" checkbox I've missed, or am I just doing it wrong?

Yeah, I think you're "doing it wrong" as much as I hate to say that, sorry. Search is keyword-based, like large-scale search is pretty much anywhere. Expecting "specifications" to match "spec" is expecting too much, same as expecting half your search to match a folder and the other half to match a file the folder is in. The main thing to keep in mind is that search is content-based, not just filename. So instead, sea…

True, although this is Google we're talking about and Google [web] search is smart enough to do a lot of statistically-driven NLU-type things on top of pure keywords...

(I currently work at Google, but not in Search or Drive / Docs...)

Re: High-documentation, low-meeting work culture

#320

Post by carom »

origin_path wrote: post #88

I tried to create this type of culture at my last gig, where I had the unusual privilege of being able to hire almost the entire engineering team, alongside my manager who was also very document oriented. Unfortunately, it didn't work out. Maybe Tremendous has done tremendously better, it's certainly possible, but here is a list of things that went wrong, maybe it's useful. 1. Standard interviews don't assess reading…

Does a README in every folder in a Github repo meet the requirements? What is the lowest friction way to do this?
Post reply on HN