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

441–450 of 524 posts

Re: High-documentation, low-meeting work culture

#441

Post by peterbozso »

splittingTimes wrote: post #426

Is there any way to achieve this within Microsoft's suite? Sadly we adopted Microsoft O365, SharePoint, Teams. How can you organize the org effectively is beyond me, how does MS do it? Are they actually using their own tools they sell others? In our org, some departments/teams/sites have just a SP, Others have a teamspace with separate SP/document store. Worse, any meaningful file structure/hierarchy you come up with…

Ex-Microsoft, current GitLab employee here. The way you describe using Microsoft's tools in your company is pretty much how things worked at Microsoft while I was there 3 years ago. If you'd like to build a handbook similar to GitLab's, this page of our handbook can be a great starting point: https://about.gitlab.com/company/culture/all-remote/handbook...

Re: High-documentation, low-meeting work culture

#442

Post by chocolatemario »

futureproofd wrote: post #28
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…

Do we work for the same company? :P Confluence has been the bane of my attempts in finding any relevant docs. Which one is the source of truth? Which one was a draft written by an overly eager to make a first impression, new employee (who is no longer with the company)? Don't even get me started on saving meeting notes to confluence. These days, I maintain my own knowledge base on Obsidian. If there's ever any confus…

I do the same except in org mode. I’ll export to markdown as needed but generally publishing documents is a secondary goal to empowering and decreasing the burden on myself.

Design docs for each and every feature has turned out not to scale for my current team. Larger, multi team features demand consolidated documentation, but for internal changes we rely on quick meetings as code reviews. Part of me misses the ceremony of the round table discussions, but the real difficulty is keeping track of why changes happen. Documenting processes and cross cutting concerns is a must have, but keeping track of all changes across quickly moving teams… it’s no surprise so many teams are just rife with tribal knowledge.

Re: High-documentation, low-meeting work culture

#443

Post by unnah »

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…

So basically you have to search google docs like you used to search the web before google came along and revolutionized search?

Re: High-documentation, low-meeting work culture

#444

Post by koonsolo »

tgsovlerkhgsel wrote: post #186
koonsolo wrote: post #160

Earlier quoted context omitted.

That is indeed too technical. Try to explain how inserting an image is not just copy paste.

Make it copy-paste. Automatically upload it to the image blob storage and insert the image code, then show the WYSIWYG preview.

Sure, and then the question comes of why you have a separate editor and preview, and you finally end up with a WYSIWYG editor.

Re: High-documentation, low-meeting work culture

#445

Post by koonsolo »

rcarr wrote: post #183
koonsolo wrote: post #160

Earlier quoted context omitted.

That is indeed too technical. Try to explain how inserting an image is not just copy paste.

1. Paste image into assets folder. 2. Write ![imagename](imagename.jpg). It's not that hard really is it.

I can already picture it: "Hey rcarr, how do you insert a picture again?" "With ![imagename](imagename.jpg)" "My image is not showing up!" "Let me take a look at it..., oh, it seems you mistyped the filename", "Oh yeah, sorry about that".

Welcome to the world of non-technical people.

Re: High-documentation, low-meeting work culture

#446

Post by koonsolo »

rcarr wrote: post #208
vasco wrote: post #191

Earlier quoted context omitted.

Have you worked with non-technical teams, ever? Perhaps in teams of very young and gamer-type people this would work, but in any real world team I've been in, this would not in fact be easy unless there's a real time preview and a button you can click that auto-generates that snippet. People would forget the exclamation mark, mixup the brackets with the parenthesis, not know how to reference the right path to the ima…

Well presumably this would be less of an issue if you had easy to use, easy to search and easy to maintain documentation, you know, maybe in the form of markdown files with a search bar where you could type 'how to paste image into documentation' in case you forgot... At the end of the day, if you've got someone who can't work out how to drag a file into a folder and then type ![imagename](imagename.jpg) after you've…

At the end of the day, if you've got someone that can't figure out there are people that are not good at technical things, do you really want them to develop your user facing software?

Re: High-documentation, low-meeting work culture

#447

Post by koonsolo »

pxc wrote: post #415
phailhaus wrote: post #403

Earlier quoted context omitted.

"I want to insert an image." Whoops, you're already in deep trouble. "I want to resize it." Even worse! These are table stakes features that everyone expects to work out of the box. If you don't give them a WSIWYG editor that does all of this for you automatically, it's DOA.

You don't need WYSIWYG for dragging and dropping images into a document, or even for resizing them. WYSIWYG is an approach to layout and formatting, not the only alternative to writing LaTeX in a terminal-bound text editor.

You are probably arguing with another developer here. Imagine having this same discussion with some business person who uses MS Excel and Word all the time, and trying to convince them that your text only thing where you can't easily add a chart coming from Excel is better than what they are currently using.

Would love to see how that conversation goes.

Re: High-documentation, low-meeting work culture

#448

Post by anhner »

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…

> Expecting "specifications" to match "spec" is expecting too much

When I use Google to search the whole web, it DOES match. So how come it doesn't work when I search a small document?

Re: High-documentation, low-meeting work culture

#449

Post by mr_gibbins »

jrochkind1 wrote: post #264
mr_gibbins wrote: post #128

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

what's a butter robot? (I feel like i'm setting up a punchline for a joke somehow...)

Sorry, should have been clearer - butter robot from Rick and Morty. An entity who has one menial job to do and that is the reason for their existence.

In this sense it was meant that the technological solution - auto documenter tools, etc - they're the butter robots. I was making the point that rather than just shim Yet Another Tool into the stack to do a single but important job (pass the butter / write the docs) perhaps give it to a human who will a) do a much better job and b) reduce the complexity of the stack.

Apologies for the confusion.

I'm surprised how this comment thread took off. Looks like there's plenty of support for AND against. I simply meant to make the point that for some problems humans do better than machines and it can be more efficient in the long term to look away from a tech solution to a human problem.

Re: High-documentation, low-meeting work culture

#450

Post by origin_path »

carom wrote: post #320
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?

Probably not IMO, it's very unlikely your source tree is structured the same way good docs should be. Docs are often task oriented, code is usually component oriented.
Post reply on HN