Live data from Hacker News

High-documentation, low-meeting work culture

tremendous.com

301–310 of 524 posts

Re: High-documentation, low-meeting work culture

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

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

Re: High-documentation, low-meeting work culture

#302

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…

The way I did this at a company I worked for is that we had a MediaWiki. That's the software that runs Wikipedia. Whenever anyone would ask me a question, I would make a MediaWiki page or add to an existing page and appropriately link the page or entry to other relevant pages and answer the question there. Then I would send them a link to the MediaWiki page. This was super efficient. Whenever any documentation was wrong, I would update it.

Re: High-documentation, low-meeting work culture

#303

If you have a high-documentation culture, you must have documentation enforcer roles. It's crazy to think you would have a library without librarians to run it. There must be people who sole role in the company is to spend time on each team (in sequence) trying to follow or review their docs and get X running "like the docs say" This group of enforcers will contain a variety of people from tech, legal, customer servi…

Unless the documentation enforcer has power, they'll just be an annoying voice. I don't care what that documentation enforcer has to say if my boss prioritizes code over documentation. You'd need management buy-in at every level for a high-documentation culture/company to work.

Sure, replace documentation enforcer with security team. Same argument.

Re: High-documentation, low-meeting work culture

#304
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 might be stupid question but why nobody has not built this kind git-based system to nontechnical people.

There's Gollum, which powers the built-in wikis on GitLab and GitHub. Its web UI handles making commits for you.

Re: High-documentation, low-meeting work culture

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

> 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 nontechnical people complain about the Confluence wiki. From their perspective, everything Just Works.

This has not been my experience at all. I've had tons of business analysts join in the Confluence moaning during meetings, both for editing and trying to find stuff. 'Just works' is not how I or anyone I worked with would describe it.

>all the things that they can't do because of Markdown's limitations

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

> how much harder it is to do drop-dead simple things like adding tables.

This has been a solved problem for a while now. One of the very first Obsidian plugins was the advanced tables plugin which makes it super easy to make and edit tables. There's also other apps like Table Flip. I'm sure there's probably plugins for other editors like VS Code or Table functionality built in to other markdown editors.

The only reasonable point you've got is about git. Like I said in the original post, a WYSIWYG web interface for non-technical folks which just auto commits would be preferable whilst still allowing regular git and markdown for technical folks. There's also nothing stopping anyone from doing an intermediate page if conflicts are detected with a three way conflict resolution page a la Jetbrains Editors with a magic wand auto solve. Maybe the WYSIWYG editor could automatically update if changes are detected a la Google Docs. There are lots of potential ways of solving the 'git hard' issue. There is also the built in Obsidian Sync and Publish which use git behind the scenes and give you access to full version history although I don't know if they scale well or not.

At the end of day, conflicts in documentation are less of an issue when they do happen because they're not going to cause an entire crash of a program, you're just going to have some text that doesn't make sense. In the very worse case scenario non technical people could just copy and paste things back into place from git history. Other than time wasted, it's not the same disaster as if a code conflict is not resolved properly.

Re: High-documentation, low-meeting work culture

#306

Earlier quoted context omitted.

> I know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writin…

> This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow Try explaining that they can't push to the repo because they cloned the http URI and need to generate an RSA token and use SSH instead. Better yet, try to figure out that's the problem when they give you a totally unhelpful version of what the pr…

Or just download Github Desktop onto their machine and show them how to use it.

Re: High-documentation, low-meeting work culture

#307
post #269

Earlier quoted context omitted.

Non-technical people used to learn bits of HTML just to get sparkly backgrounds on their MySpace pages. Markdown is absolutely masterable by anyone.

> Non-technical people used to learn bits of HTML just to get sparkly backgrounds on their MySpace pages. I'm going to take a slightly different interpretation of your comment because I think it's an interesting discussion: are the non-technical people of today less technical than the non-technical people of the MySpace days? From what I have observed, I would say yes. If you took the bottom 10% of users back then, y…

There were tons of users in the 90s who didn't have a clue how to use a computer—I mean even at a very rudimentary level—and just followed memorized or written-down steps, getting lost almost immediately if anything went wrong. Luckily for them, software was way less likely to throw up "what's new" modals seemingly at random, interrupting whatever they were trying to do, back then :-/ (edit: or to "improve" [pointlessly re-arrange] their UI while the user was away from the computer, for that matter)

If there are more of them now it's probably because computer use expanded 100 fold since then, at least, and the largely self-selected 90s users of the Web, especially, tended to have greater-than-average interest in learning computer crap, so a high proportion of new users were the can't-or-don't-want-to-learn sort. In the 90s a computer still might not be the centerpiece of an office worker or middle manager's desk, and most folks used computers very little at home, if they even had one (data I'm seeing indicates % of households in the US with a computer only hit 50% in 2000).

Re: High-documentation, low-meeting work culture

#309
post #259

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…

There are some really nice git-based wiki systems out there, and one is built into GitHub and GitLab. If you want that type of workflow for your wiki, it's easy to get.

A couple of jobs ago (so we’re talking like late 00s) I rolled an internal wiki system on top of mercurial.

It was a directory of files - I think plain text with a few wiki shortcuts, but might have been some sort of early Markdown.

The editing form was basically a text area on top of mercurial.

Similarly things like the edit log were basically dumping the mercurial output into html.

No clue how long it lasted, but it was still in regular use when I left in 2012.

Wrote the whole thing in a few afternoons.

Re: High-documentation, low-meeting work culture

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

Does using Git contribute anything of value to the documentation that you could not possibly get without git? The answer is, of course: no. You just want it because it's familiar to you. Which is fine... if you were the only person using it. Confluence is actually the best solution, hands down. It has a WYSIWYG. It supports Markdown. It has an API. It versions all content. It has fine-grained access control. It does…

No post body was provided.
Post reply on HN