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

271–280 of 524 posts

Re: High-documentation, low-meeting work culture

#271

Post by spydum »

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

Probably a text to speech fail (edit: errr speech to text). Bot or robot == butter robot

Re: High-documentation, low-meeting work culture

#272

Post by hinkley »

vsareto wrote: post #246
jasmer wrote: post #118

Earlier quoted context omitted.

It's shocking how many people don't have the ability to organize their thoughts. I'm ashamed that I was completely guilty of this myself. At some degree of professional development in software, you start to verbalize things, so as to 'explain them to yourself' and it helps clear things up. This helped me understand that 'writing skills' (in this context) are frankly more matter of being able to organize concepts more…

> It's shocking how many people don't have the ability to organize their thoughts. It's organized for them, but not for others. This skill is not intuitive to learn, so it shouldn't be shocking.

Lately I've been trying to explain to people that the Category Error they make is that we have memorized our own code, but when we look at the code of others it all has to fit into working memory. It's very hard to anticipate how other people will see your code.

One of the advantages of mentoring people is that you can run User Studies whenever you want. Tell them what the code is for and what you want them to do, and then watch them try to figure it out themselves, see how far they can get before you have to stop the experiment (due to them getting frustrated).

Re: High-documentation, low-meeting work culture

#274

Post by rcarr »

phailhaus wrote: post #258
rcarr wrote: post #233

Earlier quoted context omitted.

Not really because if you're using Obsidian you can just copy paste images and it will handle the syntax and moving the asset into the correct location anyway. 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? Seems like a pretty big pay off for not a lot of staff training.

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

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 never got written as a result. If this is the experience for technical people, what on earth is the experience like for non-technical people?

Re: High-documentation, low-meeting work culture

#275

Post by FridgeSeal »

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

It’s a reference to this: https://youtu.be/X7HmltUWXgs

Re: High-documentation, low-meeting work culture

#276

Post by rcarr »

eastbound wrote: post #245
goatlover wrote: post #210

Earlier quoted context omitted.

So you're replaced something that's simple as paste in office documents with two separate steps, one outside the app requiring the user to navigate to the assets folder, and the second requiring remembering specific syntax.

“Stop, you were born with computers so you don’t notice it, but I’m not technical enough to paste an image in a Word document.” — The intern I just had to fire last month. She pretended because her generation was born with iPhones, that knowing advanced computer skills like Cmd+V was something that wasn’t a given at 21 years old. It blew my expectations about school - but at least school teaches them to find unexpect…

Exactly, there is a certain level of basic technical competence you have to have to work any position, not just computer based ones. No-one is suggesting you have to do it all alone but if you're not willing to put the effort in and learn, or able to carry out a task after repeatedly being shown how then you're the wrong person for that job.

Re: High-documentation, low-meeting work culture

#277

Post by bazmattaz »

pmoriarty wrote: post #249
namdnay wrote: post #131

Earlier quoted context omitted.

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

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

Re: High-documentation, low-meeting work culture

#278

Post by phailhaus »

rcarr wrote: post #274
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…

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 perspective, everything Just Works. Imagine having to tell them all the things that they can't do because of Markdown's limitations, and how much harder it is to do drop-dead simple things like adding tables. Can't you see how that's a 100x higher barrier than anything you can complain about for Atlassian? Anything that you're frustrated at with their editor, you probably can't even do in Markdown. All the markdown stuff is easy.

Re: High-documentation, low-meeting work culture

#279

Post by bornfreddy »

triceratops wrote: post #152
EFreethought wrote: post #107

Earlier quoted context omitted.

> The only use case for Confluence is when you want to hide information, but credibly claim that it's documented. That describes Sharepoint more than Confluence.

Sharepoint is what you settle for when you can't convince your company to spring for Confluence.

Sharepoint is what you settle for when you hate the company, coworkers and yourself.

Re: High-documentation, low-meeting work culture

#280

Post by Sohcahtoa82 »

dottedmag wrote: post #4

Is there a way to stop scrolling hijacking on the sites like this one?

Honestly, if it wasn't for the fact that setting up a build environment in Windows is a god awful experience (As opposed to *nix where I can just "apt install lib-dev", I'd fork Firefox and make a build that strips out access to scrolling in JavaScript.

Dear Web Devs

Every web browser already does smooth scrolling out of the box. Your JavaScript implementations of it rarely work and only create frustration to users. Even they they DO work, it creates an unexpected behavior, which is frustrating.

Post reply on HN