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

321–330 of 524 posts

Re: High-documentation, low-meeting work culture

#321

Post by _joel »

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…

Well there is (ftr I dislike confluence, but come on) https://marketplace.atlassian.com/apps/1216387/approvals-for...

Re: High-documentation, low-meeting work culture

#322

Post by Aeolun »

lukewiwa wrote: post #315
origin_path wrote: post #132

Earlier quoted context omitted.

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.

I mean. I guess? The difference between having it written down in Confluence and disappearing into the ether is academic though. Either way nobody will ever find the information again.

Re: High-documentation, low-meeting work culture

#323

Post by Aeolun »

neura wrote: post #87
futureproofd wrote: post #28

Earlier quoted context omitted.

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…

So you are now the gatekeeper?

Maybe more like the font of knowledge?

Re: High-documentation, low-meeting work culture

#324

Post by Viliam1234 »

ericmay wrote: post #135
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?

> 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.

Re: High-documentation, low-meeting work culture

#325

Post by Viliam1234 »

lukewiwa wrote: post #315
origin_path wrote: post #132

Earlier quoted context omitted.

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.

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

A better solution might be that anyone can write the documentation, and there is a maintainer who constantly refactors the wiki to keep it legible. Makes sure the information is not duplicated, adds hyperlinks to things, etc.

Re: High-documentation, low-meeting work culture

#326

Post by Frotag »

dia80 wrote: post #13
skagenpilot wrote: post #6

This reminds me of Alan work culture [1], Alan is a startup with a zero meeting policy and a very strong culture of writing. They check the quality of one's writing during their interview process. Alan leaders also have other strong ethos like "no managers" and "complete transparency". I really wonder if these companies are exceptions or if this organisationel model could be replicated more widely. I guess it caters…

To me, some of the benefits of having the occasional meeting is to create a shared understanding of what's going on and also to enable a vigorous group discussion. I'm not sure I would know how to replicate that with writing alone.

Chatrooms for each team, but visible to other teams. And a culture of encouraging technical discussion to be summarized or at least alluded to in the public chat. I'm sure this doesn't scale, but for a company of <20 developers, this worked amazingly. It was also great for finding answers to silly questions without having to bug someone.

Re: High-documentation, low-meeting work culture

#327

Post by beachy »

The_Colonel wrote: post #250
heydonovan wrote: post #237

Earlier quoted context omitted.

Disagree. A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. I've seen those small ad-hoc changes cause havoc because someone forgot to escape a single quote or didn't realize tabs were necessary and replaced them with spaces. The default for Confluence is just that, everyone commits at will. There is no structure, tons of duplication, no standards…

> 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.

Re: High-documentation, low-meeting work culture

#328

Post by impute »

skagenpilot wrote: post #6

This reminds me of Alan work culture [1], Alan is a startup with a zero meeting policy and a very strong culture of writing. They check the quality of one's writing during their interview process. Alan leaders also have other strong ethos like "no managers" and "complete transparency". I really wonder if these companies are exceptions or if this organisationel model could be replicated more widely. I guess it caters…

There's nothing on that page that mentions "no managers"

Re: High-documentation, low-meeting work culture

#329

Post by diordiderot »

vlmutolo wrote: post #301
ravenstine wrote: post #175

Earlier quoted context omitted.

I wouldn't even bother with the static site generator. While I like the idea of STGs, in my opinion, they all suck. And now there has to be someone to maintain how those pages are rendered and know how whatever thing like Jekyll works. Just let developers either read the markdown files as-is or set their IDE to render markdown previews by default. I prefer the latter because I don't have to wait for someone who's on…

Rust's rustdoc tool does an excellent job converting comments to HTML. The documentation for almost every public Rust library is automatically rendered and hosted on docs.rs and it's incredible to have that consistency. Just check out this Regex type and the awesome documentation for every method, all taken from inline comments: https://docs.rs/regex/latest/regex/struct.Regex.html

I wish more languages had this!

Re: High-documentation, low-meeting work culture

#330

Post by daeminsong »

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...)

Thanks for asking this. Was too afraid to ask haha.
Post reply on HN