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

331–340 of 524 posts

Re: High-documentation, low-meeting work culture

#331

Post by albedoa »

phailhaus wrote: post #278
rcarr wrote: post #274

Earlier quoted context omitted.

Because I'm tied into Atlassian's ridiculous way of doing things as opposed to a completely open file format I can take anywhere and edit in any number of editors. I have empathy for non technical people in that I believe Markdown is far easier to use than Atlassian's interface. Every single developer I've worked with has been tearing their hair out when trying to write documentation on Confluence and documentation n…

> Because I'm tied into Atlassian's ridiculous way of doing things as opposed to a completely open file format I can take anywhere and edit in any number of editors. Nobody cares. Really, they do not. This doesn't help the business, it adds way too much overhead, and requires nontechnical people to understand markdown and git . I have never heard nontechnical people complain about the Confluence wiki. From their pers…

> I have never heard nontechnical people complain about the Confluence wiki. From their perspective, everything Just Works.

This is where you lost me and probably many who are following your comments. I have never heard anyone express what you just did about Confluence.

I don't know what accounts for the difference between our experiences, but I work with many nontechnical people, and they have a much different opinion than those who you are listening to. I certainly have never heard anyone say that everything Just Works.

Re: High-documentation, low-meeting work culture

#332

Post by jmspring »

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 of the biggest issues with large companies is - there could be a lot of documentation- but can you find it.

A lot comes from tribal knowledge/who to talk to/etc.

Re: High-documentation, low-meeting work culture

#333

Post by still_grokking »

bazmattaz wrote: post #277
pmoriarty wrote: post #249

Earlier quoted context omitted.

Most developers just don't like writing docs, are too busy to write them, and aren't very good writers anyway. So even on those rare occasions when they do actually document something, the documentation tends to be pretty bare-bones and not very readable. Good technical writers are worth their weight in gold.

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.

Re: High-documentation, low-meeting work culture

#334

Post by phailhaus »

pxc wrote: post #300
phailhaus wrote: post #258

Earlier quoted context omitted.

> But is taking an hour to read through a markdown cheatsheet really the worst thing in the world if what you end up with is far more useful and maintainable documentation? This makes no sense given that you get the same payoff by using something like Atlassian's wiki. No git, no markdown, none of this nonsense, users can just immediately hit the ground running with advanced formatting support and version history. I…

> This makes no sense given that you get the same payoff by using something like Atlassian's wiki. No git, no markdown, none of this nonsense, users can just immediately hit the ground running with advanced formatting support and version history. Except that like all WYSIWYG editors, Confluence's editor is buggy and unpredictable. You can only use it in a browser. Because it doesn't even have a 'raw' editing mode any…

> If you want technical documentation that developers are going to maintain, it has to be a joy to work with in their own editors.

Not what we're talking about here though, OP is suggesting it's reasonable to teach business analysts markdown and git for all company documentation.

Re: High-documentation, low-meeting work culture

#336

Post by phailhaus »

albedoa wrote: post #331
phailhaus wrote: post #278

Earlier quoted context omitted.

> Because I'm tied into Atlassian's ridiculous way of doing things as opposed to a completely open file format I can take anywhere and edit in any number of editors. Nobody cares. Really, they do not. This doesn't help the business, it adds way too much overhead, and requires nontechnical people to understand markdown and git . I have never heard nontechnical people complain about the Confluence wiki. From their pers…

> I have never heard nontechnical people complain about the Confluence wiki. From their perspective, everything Just Works. This is where you lost me and probably many who are following your comments. I have never heard anyone express what you just did about Confluence. I don't know what accounts for the difference between our experiences, but I work with many nontechnical people, and they have a much different opini…

What issues do nontechnical people have with Confluence that are easier in just Markdown? The typical gripes are around search and organization, not editing. Markdown would be seen as a massive downgrade in experience.

Re: High-documentation, low-meeting work culture

#337

Post by warrentr »

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…

This approach is definitely possible with a good web-based git IDE. We use gitlab's webIDE and have taught a few very non-technical (even temporary) employees how to do simple commits of markdown files (the trick here is high visibility into their commits -slack messages- and safeguards to make sure important things don't go live via CI too soon). There's a number of rough edges to sort out but this is vastly simpler, faster, more flexible etc for many situations (and amazing to not be using jira or wordpress :) )

Re: High-documentation, low-meeting work culture

#338

Post by phailhaus »

rcarr wrote: post #305
phailhaus wrote: post #278

Earlier quoted context omitted.

> Because I'm tied into Atlassian's ridiculous way of doing things as opposed to a completely open file format I can take anywhere and edit in any number of editors. Nobody cares. Really, they do not. This doesn't help the business, it adds way too much overhead, and requires nontechnical people to understand markdown and git . I have never heard nontechnical people complain about the Confluence wiki. From their pers…

> Nobody cares. Really, they do not. This doesn't help the business, it adds way too much overhead, and requires nontechnical people to understand markdown and git. They absolutely care if one day Atlassian decides to hike prices to levels they deem unreasonable and now their entire documentation is locked in a proprietary format or if Atlassian go under, are purchased by a competitor etc. > I have never heard nontec…

> They absolutely care if one day Atlassian decides to hike prices to levels they deem unreasonable and now their entire documentation is locked in a proprietary format or if Atlassian go under, are purchased by a competitor etc.

Clearly they don't. You already said that you tried to pitch your solution, and you weren't able to prove its value. Atlassian is seen as reliable, and those fears are just not worth the hassle of managing your own infrastructure.

> what are these things you're so desperate to do in Code Documentation that you can't do in markdown?

1. We're talking about using Obsidian to replace a company's entire knowledge base, not just code. Code documentation is managed by technical people.

2. What are these things that are so difficult to do in Confluence that are easier in Markdown? It's a superset!

Re: High-documentation, low-meeting work culture

#339

Post by pxc »

phailhaus wrote: post #334
pxc wrote: post #300

Earlier quoted context omitted.

> This makes no sense given that you get the same payoff by using something like Atlassian's wiki. No git, no markdown, none of this nonsense, users can just immediately hit the ground running with advanced formatting support and version history. Except that like all WYSIWYG editors, Confluence's editor is buggy and unpredictable. You can only use it in a browser. Because it doesn't even have a 'raw' editing mode any…

> If you want technical documentation that developers are going to maintain, it has to be a joy to work with in their own editors. Not what we're talking about here though, OP is suggesting it's reasonable to teach business analysts markdown and git for all company documentation.

It's unlikely that they'll actually use Git, but teaching them Markdown is absolutely doable. And any modern Git forge will let you edit a Git-based wiki in the web UI without knowing what a commit is.

Re: High-documentation, low-meeting work culture

#340

Post by stevesimmons »

Viliam1234 wrote: post #324
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…

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.

> But a different question is, why is no company trying to do this differently?

I once worked at a company - in a different domain - that made a conscious decision to make this kind of hire. It worked incredibly well, and I never understood why more companies didn't do it.

The context in my case was the Australian offices of a management consulting firm (BCG). The Melbourne and Sydney offices hired what were called "editors", brought on at the same grade as the consultants. Not editing as in correcting grammar. But helping the consultants improve the logic of the arguments in their slide decks: so they were logically consistent, easy to understand, and actually addressed the clients' issues. I was a junior consultant back then, and we were constantly pushed by our managers "have you seen Yvonne?" [the Melbourne editor] when preparing for major presentations.

Post reply on HN