I had the luxury of being able to document the hell out of the previous system that I worked built -- before, during, and after development. It was a refreshing change from 'just hurry up and build the damn thing'
High-documentation, low-meeting work culture
161–170 of 524 posts
Re: High-documentation, low-meeting work culture
#162I'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'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
This, except for normals, sort of exists:
Craft: https://www.craft.do/solutions/businesses
Default is internal only, but you can allow sharing, which creates a web URL that can be privately or publicly shared (and can be on your own custom domain).
It has versioning, it has comments, it has real time multi-editor collaboration. An entire conference room, in person and virtual, can co-edit in true real time without anything blowing up, a feat not to be tried in Word, or even Google Docs.
Most firms should stop looking and just try Craft. Encourage everyone to do everything there, see what happens.
Note bene: it happily imports markdown, also exports Word, PDF, Markdown, and Textbundle, and can feed a static site gen.
They also keep busy: https://www.craft.do/whats-new
// I use Obsidian for myself, but Craft to collaborate with non-engineers. I've also been known to recommend FOAM to engineering teams, coupled with mkdocs and a good theme for static site gen, such as material for mkdocs:
https://foambubble.github.io/foam/
https://github.com/squidfunk/mkdocs-material
For eng teams already living in VS Code, it's hard to beat PKM where you already are.
Re: High-documentation, low-meeting work culture
#163Earlier quoted context omitted.
Confluence (and all of the similar products) can be used successfully, but you need the teams to agree on and enforce a logical document hierarchy. It’s not really difficult to organize a company wiki into teams, projects, and other logical divisions if you make it a priority. The primary failure mode I see is when people just throw random documents into Confluence wherever convenient at time of writing and never go…
If using the lowest friction or default path in a tool leads to bad outcomes, that's a problem with the tool. Not the user.
You create the lowest friction/default path according to your company's needs.
There isn't a universal note taking application that comes pre-organized for your team's use case. You have to put some work into any tool you use.
Re: High-documentation, low-meeting work culture
#164I'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'm a CTO in a startup and all our docs are in .md files, mermaid diagrams with dynamic Table of Content generation.
We have two repos: Product (to anything relating to product) and Wiki (anything else, ranging from onboarding checklists, brief design documentation of key parts of the code ... to meta documentation)
Although our team is small by many standards (8) everyone likes it.
We spend a ridiculously small amount of time on meetings.
The obvious and great upside is the code/documentation integration which has virtually 0 context loss.
One downside however is indeed the difficulty of git branching to non-developers.
Once in while I find myself debugging a messed up version.
But I'm willing to pay that price.
Re: High-documentation, low-meeting work culture
#165I'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 know git can be tricky but it cannot be that difficult to teach people from non technical departments add, commit and push and then show maybe one person from each department how to solve conflicts
Nah, that's going to be a crapshoot. You want a few people who know git and do this for a full time job and that's all they do - manage the documentation git repo.
Re: High-documentation, low-meeting work culture
#166In order for this to work, you also need a high-reading work culture, which is distinct from a high-writing (documentation) work culture.
well if people choose not to read or engage with documentation, they're only hurting themselves. in theory, their work performance will suffer when compared w/ others. and if it doesn't, then they for some reason just don't need to engage with existing documentation, so high-reading wouldn't really matter. the consequences of not reading documentation will either become clear or it won't
Poor work performance hurts everyone.
Re: High-documentation, low-meeting work culture
#167Earlier quoted context omitted.
No, code actualizes the intent of the documentation and the product. The natural language description of a product shouldn't need to be discarded in lieu of some machine language. The lingua franca of ideas is natural language.
Fair enough, but you still end up with 2 separate ways to express things. And I have yet to see a company that changes the documentation first and then derives code changes from that. Usually tickets are written, code is changed. Updating existing documentation is an afterthought at best. Personally I prefer any formal or semi-formal documentation (e.g. Swagger) over a Confluence page any time of the day.
I built this documentation/testing framework to do just that: https://hitchdev.com/hitchstory
I realized one day that the specs, tests and how-to markdown documentation I wrote all used the same examples.
From that I derived the idea to create a "spec" DSL that could both be run as a test and generate markdown (with screenshots, etc.) to make nice high level how-tos.
Cucumber has the same sort of idea but the DSL really isn't suitable.
Re: High-documentation, low-meeting work culture
#168Earlier quoted context omitted.
People hate reading bad writing. As someone who dabbled in creative writing before discovering my vocation, I see a lot of problems caused by people not bothering to explain themselves clearly. As my time in the industry grew I begin to see people who were confused about their own ideas and came to see how many things we don’t even explain to ourselves. Which likely plays a role in how defensive people get about some…
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 funny how AI and humans struggle with similar issues of doing things intuitively and being unable to explain themselves.
Re: High-documentation, low-meeting work culture
#169"Unfortunately, Tremendous is not available in the country where you are located. If this is a problem, please contact support@tremendous.com." I'm in Ukraine and this is disgusting.
US treasury department regulations prohibit US companies from working with people and companies in Russian-controlled parts of Ukraine. Unfortunately, IP geolocation is accurate only to the country level, so US companies have no choice but to block the entire country to comply with regs.
This is the first case I know of. I never get such issues here in central Ukraine. This is because occupied regions always present themselves as Russia, not Ukraine. If something says that it is Ukraine, it's a sure sign that it is NOT occupied by Rissua.
Re: High-documentation, low-meeting work culture
#170I'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'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git
I had the same concern, internal documentation should be in a portable format... and I managed to mostly successfully get us to change to MD text files in a git repo.
I, and others, were tired of it being locked up in proprietary platforms like google docs - which ironically has terrible search capability and is horribly slow. Some of the devs already wrote documentation in markdown and plain text along side code (Also I hear talking about yourself in the 3rd person is the first sign of madness). So a git backed wiki in text files was what I wanted. But it also needed to generate commits from the front end for the less technical, and preferably needed oauth to delegate access control to some other system.
"Golumn" filled this space first I believe, but doesn't (or didn't at the time) have the commit or oauth capability. So I settled on a fork "Jingo" which does. I'm not completely wedded to Jingo, which is a nodejs app, I haven't dug too deeply into it and so my confidence in it is unknown... but this is effectively data driven design, md text files in git... the code (which is not part of the same repo) is disposable.
I set this up 3 years ago and haven't touched it at all. This has been mostly successful gaining more traction over time. People who have no clue how to use git are generating gits commits on a daily basis through the front end - others are using the repo directly. Google docs still has it's place for arbitrary word type stuff, but most internal internal reference type material now gets put into the wiki as a preference, since it's way more searchable, and orders of magnitude faster to access.
[edit]
To be clear, i'm in a small company where it's easier to change or try things like this.
I also got the same expected pushback, concern over MD being too limited compared to google docs and the solution being too technical. but if you can just convince people to trial it for long enough with an exit plan, they will usually obtain a more balanced view weighing the tangible benefits more highly and weighing the negatives or concerns less after actually experiencing it... in this case most people realise that all the bells and whistles of google docs are not critical, and the benefits of the searchability, speed and portability are huge.