High-documentation, low-meeting work culture(tremendous.com)
tremendous.com
High-documentation, low-meeting work culture
https://www.tremendous.com/blog/the-perks-of-a-high-documentation-low-meeting-work-culture
522 comments
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 specific, obscurely named document in Google Drive, Confluence, or Github. We've tried a bunch of search tools which successfully surface the million product documents, design documents, PM reports, planning docs, retro docs and standup and oncall notes related to any feature, none of which are up to date.
I would suggest introducing two things.
First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.)
Second, I would introduct the idea of a Documentation Portfolio. I have a review of Agile Documentation at https://www.ebiester.com/documentation/2020/06/02/agile-docu... and it speaks to another structure for how to build the documentation in a more reliable form and thinking more carefully about your audience for a particular type of documentation.
First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.)
Second, I would introduct the idea of a Documentation Portfolio. I have a review of Agile Documentation at https://www.ebiester.com/documentation/2020/06/02/agile-docu... and it speaks to another structure for how to build the documentation in a more reliable form and thinking more carefully about your audience for a particular type of documentation.
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?
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 question why not make twice as much working as a software developer and not have to sort out these types of messes?
Also job security. Anyone doing this work full-time is the first on the chopping block, and developers who are working on documentation tend to be perceived as lower status since they aren't delivering features.
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 question why not make twice as much working as a software developer and not have to sort out these types of messes?
Also job security. Anyone doing this work full-time is the first on the chopping block, and developers who are working on documentation tend to be perceived as lower status since they aren't delivering features.
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? 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.
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.
I would love that job, I'm always going back to presentations and finding better ways they could have made the point and identifying missing context what they would need to be more relevant.
A previous team I was on ended up with this role. Strong writer with no technical skills joined the team and worked hand-in-hand with engineers fleshing out docs. It was productive for the engineers because they needed to articulate the ideas very clearly. The writer has been attached to that project now for 6-7 years at this point, and could probably stand in as a support engineer for some problems. It was a little painful getting HR to approve a tech writer getting paid close to an engineer position (this was after a few years).
I do like the sibling comment calling for a librarian. I imagine that would pay a ton of dividends if the librarian was motivated and got support.
I do like the sibling comment calling for a librarian. I imagine that would pay a ton of dividends if the librarian was motivated and got support.
Some companies do value technical writers and pay them as much as engineers, but they are still pretty rare.
There are three things that I think are preventing technical writing from being more widely valued:
1. Software companies tend not to distinguish between technical writers who are good at English vs. technical writers who are good at engineering, understand their audience, and can articulate complex ideas to that audience effectively.
2. Technical writers who are good at English make about half as much as technical writers with engineering skills, but they also muddy the hiring waters and drag salaries down for everyone else.
3. Most corporate-people think because they can type up a decent email they can write technical documentation themselves. They're usually wrong on both counts.
There are three things that I think are preventing technical writing from being more widely valued:
1. Software companies tend not to distinguish between technical writers who are good at English vs. technical writers who are good at engineering, understand their audience, and can articulate complex ideas to that audience effectively.
2. Technical writers who are good at English make about half as much as technical writers with engineering skills, but they also muddy the hiring waters and drag salaries down for everyone else.
3. Most corporate-people think because they can type up a decent email they can write technical documentation themselves. They're usually wrong on both counts.
As a tech writer, I think this is because it's hard to concretely quantify the value that a tech writer brings, and thus it's hard to make a clear business case for.
> differently? Like, hiring one good tech writer to maintain the company documentation
He assumes that "full understanding (into every detail) of what is being documented is needed" (as I put it). So, the new hire will never get it right 100%. he will both struggle and annoy others (to forever enlighten him), which is a fair point.
But it is not black or white. Others here have more positive experiences
He assumes that "full understanding (into every detail) of what is being documented is needed" (as I put it). So, the new hire will never get it right 100%. he will both struggle and annoy others (to forever enlighten him), which is a fair point.
But it is not black or white. Others here have more positive experiences
Probably not the same pay as developers but the scenario you describe is already true in most regulated industries, where some regulated body actually asks for the docs on any given product.
> 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.
This comment is absolutely true and many, of not most, companies fail to understand it. I think the problem stems from corporate-people thinking, "Why should I pay a writer when we all speak English (or whatever language) and can write it ourselves." And that's why so many companies have shitty documentation.
> ...so that begs the question why not make twice as much working as a software developer and not have to sort out these types of messes?
I was a software engineer for 30+ years and got completely burned out on it, so I left engineering to do technical writing. So far, I like it much better because I have far more control over my time. In my experience so far, the sorting-out-messes work is about the same in either field. Both jobs are pretty complex. I also make exactly the same as I did while working as an engineer.
I think the secret to not being first on the chopping block is to show you're delivering value to customers and internal teams. At least I attribute that to my survival through multiple layoffs so far.
This comment is absolutely true and many, of not most, companies fail to understand it. I think the problem stems from corporate-people thinking, "Why should I pay a writer when we all speak English (or whatever language) and can write it ourselves." And that's why so many companies have shitty documentation.
> ...so that begs the question why not make twice as much working as a software developer and not have to sort out these types of messes?
I was a software engineer for 30+ years and got completely burned out on it, so I left engineering to do technical writing. So far, I like it much better because I have far more control over my time. In my experience so far, the sorting-out-messes work is about the same in either field. Both jobs are pretty complex. I also make exactly the same as I did while working as an engineer.
I think the secret to not being first on the chopping block is to show you're delivering value to customers and internal teams. At least I attribute that to my survival through multiple layoffs so far.
> I was a software engineer for 30+ years and got completely burned out on it, so I left engineering to do technical writing
How did you make this transition? Any credentials/certifications you needed? Did you transition within the same company?
How did you make this transition? Any credentials/certifications you needed? Did you transition within the same company?
My college degree was in writing, so I used that and a portfolio to make the transition. During interviews, it seems my software engineering experience and portfolio are more valued than my writing degree though.
Summary: HIGH Documentation = HIGH staleness + HIGH loss. HIGH staleness is because nobody wants to do it (status is lower). Also… nobody else can do it (full understanding of what is being documented is needed)
So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopeless?
PS: to solve the second loss/discovery part, I think we are heading for that AI powered simple "unified search" experience.
So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopeless?
PS: to solve the second loss/discovery part, I think we are heading for that AI powered simple "unified search" experience.
AI can't solve search. If you look at how google did it, they bullied and cajoled site owners to add detailed metadata to the top of pages. It's not magic, it's creating incentives for people to create documentation.
'bullied and cajoled' is an interesting set of verbs to use here. Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?
>Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?
Yes, there's a very good reason not to use metadata: it's extra work, and it's not very fun, just like writing docs for software. So people don't want to do it because it isn't "sexy" (and there aren't very good incentives to overcome people's reluctance to do that work).
Because of this, just like any job that people don't really want to do, you have to "bully and cajole" them into doing it.
Yes, there's a very good reason not to use metadata: it's extra work, and it's not very fun, just like writing docs for software. So people don't want to do it because it isn't "sexy" (and there aren't very good incentives to overcome people's reluctance to do that work).
Because of this, just like any job that people don't really want to do, you have to "bully and cajole" them into doing it.
A human has to write this type of metadata.
If you don't include the right metadata, google won't rank you highly. If you include the right metadata, your content will get higher rankings and the snazzy preview cards on different social media platforms.
Metadata is good! There are structural incentives to be mediocre though.
If you don't include the right metadata, google won't rank you highly. If you include the right metadata, your content will get higher rankings and the snazzy preview cards on different social media platforms.
Metadata is good! There are structural incentives to be mediocre though.
The age old issue. There's oodles of data at how people don't keep doing it because it's toil to them.
The better question to ask is if AI can do the ghost writing that high-documentation culture needs. This is an interesting hypothesis for GPT-4
First, I’m assuming the documentation is already updated (i.e., 1st part is OK = no staleness)
Second, the whole point of AI NLP search (i.e., 2nd part = loss) is that it does not need metadata (which was the basis of the now mostly abandoned semantic web approach to KM).
Second, the whole point of AI NLP search (i.e., 2nd part = loss) is that it does not need metadata (which was the basis of the now mostly abandoned semantic web approach to KM).
You need to
1) Link to the documentation in your tools
2) Ensure everyone has edit access to the linked documents
1) Link to the documentation in your tools
2) Ensure everyone has edit access to the linked documents
A feature of docs-as-code is having the (typ. markdown) docs live in the code directories. Leaving no excuses for tech people not to update them, or at least insert a TODO.
Another idea might be, whenever a new feature is closed out, auto-allocate some percentage of its implementation time to documentation, and schedule an interview with a tech writer.
Another idea might be, whenever a new feature is closed out, auto-allocate some percentage of its implementation time to documentation, and schedule an interview with a tech writer.
What you probably really want is a librarian (with some degree of technical background). We at least had one for a while for our sales/marketing docs--which are separate from customer-facing technical docs.
> 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.
Library science is a popular area of study but the job market isn’t great and neither is the pay. Lots of people to choose from here even without poaching from existing libraries.
Library science is a popular area of study but the job market isn’t great and neither is the pay. Lots of people to choose from here even without poaching from existing libraries.
> you can't really hire someone off the street to do it effectively.
I disagree, I've been apart of a few companies that have done exactly this. I would suggest not presenting this argument as an absolutism.
I disagree, I've been apart of a few companies that have done exactly this. I would suggest not presenting this argument as an absolutism.
Usually a tech writer is also some sort of PM role that gets to chase developers and get them to explain what's in their head. Sometimes you have to have such a person on board.
I once did an internship that involved chasing down senior devs and generating documentation for them (needed for FIPS certification). It was a great way to learn about the tech stack. Suffice it to say I didn't have any PM role at all.
I'm not saying a technical writer should have a PM role, but it's a similar role
In my opinion, you shouldn't ask technical writers to manage projects anymore than you would ask engineers to. Both jobs are complex enough without adding an entirely different full-time job on top of the work.
Get the brain dump when it's all still fresh in the head !
> and so that begs the question why not make twice as much working as a software developer and not have to sort out these types of messes?
You partly answered your own question: perhaps you pay the librarian/documentation writer too little? ;-)
Seriously: letting the documentation to be written by such a person won't be as much a cost-reducing measure, but instead mostly an approach to improve the documentation quality.
You partly answered your own question: perhaps you pay the librarian/documentation writer too little? ;-)
Seriously: letting the documentation to be written by such a person won't be as much a cost-reducing measure, but instead mostly an approach to improve the documentation quality.
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
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.
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.
If I'm simply consuming a library, I find most real-world documentation to be pretty superfluous. A full working example is usually enough to understand how things fit together.
If I'm working on a library, design docs and commented code is nice though.
If I'm working on a library, design docs and commented code is nice though.
It may take more time to explain it to a tech writer than it would for you to write it, but in most cases the final docs written by a tech writer will be much better.
The tech writer's output will be a Force Multiplier.
> I'm sure these are great technological answers
They're not, actually, as is obvious if you actually read the links. They're human process approaches.
They're not, actually, as is obvious if you actually read the links. They're human process approaches.
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
Haha that’s awesome. I had figured it was just a typo for “better robot.”
Since the last episode we have also a lever robot
Sorry, should have been clearer - butter robot from Rick and Morty. An entity who has one menial job to do and that is the reason for their existence.
In this sense it was meant that the technological solution - auto documenter tools, etc - they're the butter robots. I was making the point that rather than just shim Yet Another Tool into the stack to do a single but important job (pass the butter / write the docs) perhaps give it to a human who will a) do a much better job and b) reduce the complexity of the stack.
Apologies for the confusion.
I'm surprised how this comment thread took off. Looks like there's plenty of support for AND against. I simply meant to make the point that for some problems humans do better than machines and it can be more efficient in the long term to look away from a tech solution to a human problem.
In this sense it was meant that the technological solution - auto documenter tools, etc - they're the butter robots. I was making the point that rather than just shim Yet Another Tool into the stack to do a single but important job (pass the butter / write the docs) perhaps give it to a human who will a) do a much better job and b) reduce the complexity of the stack.
Apologies for the confusion.
I'm surprised how this comment thread took off. Looks like there's plenty of support for AND against. I simply meant to make the point that for some problems humans do better than machines and it can be more efficient in the long term to look away from a tech solution to a human problem.
Thanks for asking this. Was too afraid to ask haha.
Probably a text to speech fail (edit: errr speech to text). Bot or robot == butter robot
I’ve advocated for hiring a librarian but I haven’t ever been able to make the case successfully. So yes, I agree with you, but the “how” of structuring and the “who” are orthogonal.
This is about prioritizing the documentation you write.
This is about prioritizing the documentation you write.
> Why not employ a technical writer/documenter/whatever job title you like
Who would supply that person with the information required to write the documentation?
Who would supply that person with the information required to write the documentation?
Subject matter experts, to the extent that the writer isn't one already.
In my opinion, companies should hire subject matter experts who can write rather than just someone with an English degree. I've fixed a lot of terrible documentation written by English majors with no engineering background.
In my opinion, companies should hire subject matter experts who can write rather than just someone with an English degree. I've fixed a lot of terrible documentation written by English majors with no engineering background.
I came here for the butter robot.
Er, the butter robot joke was a throwaway line about the exential crisis of a robot that carries butter, not a blueprint or metaphor about how to conduct software development, please for all that is holy don't try to read more into that than is there...
What's the difference between Diataxis and the Divio documentation framework? https://documentation.divio.com/
Seems like the Diataxis author came up with the framework while working at Divio: https://github.com/evildmp/diataxis-documentation-framework/...
Indeed, they look identical, even down to the font used.
Diataxis seems to be a fork of Divio.
But according to the network graph on GitHub, Diataxis seems to be more active, although both of them still receive updates.
But according to the network graph on GitHub, Diataxis seems to be more active, although both of them still receive updates.
From the GitHub page, it looks like Divio is actually a fork of Diátaxis.
divio/diataxis-documentation-framework is forked from evildmp/diataxis-documentation-framework, and evildmp is Daniele Procida, the creator of the latter repository and the maintainer of diataxis.fr.
divio/diataxis-documentation-framework is forked from evildmp/diataxis-documentation-framework, and evildmp is Daniele Procida, the creator of the latter repository and the maintainer of diataxis.fr.
Thanks for the investigation!
Diataxis looks fantastic. That chart on the home page is absolute gold.
Thanks so much for the link, I wish I'd had that chart ten years ago!
Thanks so much for the link, I wish I'd had that chart ten years ago!
Whoa! I love a good 2x2, and the one on the Diataxis home page is great!
Adding a caption here for anyone on a screen-reader, before I give commentary on it:
Also, I wonder if the relative distributions of each one could tell you something about the team's health — or even just the kind of work the team does?
For example, between two teams who are both documentation-heavy, what does it means if one team's docbase is 80% tutorials, whereas the other team's is 80% reference guides? It would be fascinating if anyone's already given thought to relative metrics/heuristics like this.
Adding a caption here for anyone on a screen-reader, before I give commentary on it:
* X-axis: "serve our study" vs "serve our work"
* Y-axis: "practical steps" vs "theoretical knowledge"
* which gives 4 quadrants: how-to guides, tutorials, explanation, and reference
Also, I wonder if the relative distributions of each one could tell you something about the team's health — or even just the kind of work the team does?
For example, between two teams who are both documentation-heavy, what does it means if one team's docbase is 80% tutorials, whereas the other team's is 80% reference guides? It would be fascinating if anyone's already given thought to relative metrics/heuristics like this.
Almost every developer I've ever seen defaults to "explanation." Reference is there to the extent that it can be auto-generated, but most companies are relatively light on reference. Tutorials are pretty rare in smaller orgs - it rarely gets prioritized.
How-tos are an interesting case. I see a lot of informal how-tos in slack. However, how-tos also are the most likely to become stale because if they're needed often enough, they tend to become automated in part or whole. It is by its very nature transitory.
How-tos are an interesting case. I see a lot of informal how-tos in slack. However, how-tos also are the most likely to become stale because if they're needed often enough, they tend to become automated in part or whole. It is by its very nature transitory.
Diataxis looks interesting thanks for the link
Wow yeah, it puts into much better words than what I've been trying to get software engineers to do for a decade or more. Really awesome resource, thanks again kind parent :)
The nice thing about this as well is that, unlike a technical framework, you can start implementing many of the ideas of this framework without any sign on from the rest of your group. And if it works, what will eventually happen is people will say "wow, capableweb rights such fantastic documentation, we should go to them and ask for their advice on how we can all write documentation that good"
The diataxis seems quite interesting.
I see how it applies to documents which describe things as they are, but I'm curious how it would classify forward looking documents like technical designs, strategy and vision documents, roadmaps, and mission statements.
I see how it applies to documents which describe things as they are, but I'm curious how it would classify forward looking documents like technical designs, strategy and vision documents, roadmaps, and mission statements.
This does not help with outdated docs.
> Confluence
There's your problem. The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.
There's your problem. The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.
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 back to logically organize anything. One symptom of this is when key information is being recorded in a hundred different people’s “Personal Space”
Taking even half a day to organize the average Confluence makes a huge difference.
The primary failure mode I see is when people just throw random documents into Confluence wherever convenient at time of writing and never go back to logically organize anything. One symptom of this is when key information is being recorded in a hundred different people’s “Personal Space”
Taking even half a day to organize the average Confluence makes a huge difference.
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.
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.
I disagree. The point of a tool is to reduce work.
Most teams and companies aren't special snowflakes that need individualized organizations, and document hierarchies. There can be such a thing as sensible defaults that you customize or tweak later (no idea if Confluence ships with that - I've only ever seen Confluence installations in their already-screwed-up state). At the same time, an inexperienced user staring at a fresh Confluence install isn't going to get the organization correct right off the bat.
If you have to put in work upfront before the tool is even halfway useful, it better be really damn good after that. Confluence is not.
Most teams and companies aren't special snowflakes that need individualized organizations, and document hierarchies. There can be such a thing as sensible defaults that you customize or tweak later (no idea if Confluence ships with that - I've only ever seen Confluence installations in their already-screwed-up state). At the same time, an inexperienced user staring at a fresh Confluence install isn't going to get the organization correct right off the bat.
If you have to put in work upfront before the tool is even halfway useful, it better be really damn good after that. Confluence is not.
Disclaimer: I am a consultant working for an Atlassian-centered consultancy. I do a lot of Confluence-based projects recently.
You would not believe how special some use-cases are, especially when you work with organisations that have highly regulated environments. I've seen anything from markdown files in a git repository being semiautomatically created in a Jenkins run to an organization having built essentially their own wiki software because nothing on the market fulfilled their need at the time (now 5 years later, they realise no-one uses that thing because it is just unintuitive). I have seen organisations that have no content oversight and some who had a whole department of "content czars", whose sole job it was to keep their documentation fresh and updated. I've seen organisations that had strict rules on approving each individual change, with complex approval workflows.
If you have never documented anything, Confluence may be overwhelming, but so will every tool that has "sensible defaults", because before too long, you will start hitting the envelope. Documentation software is not like a MacBook that you just buy and start using, you always need some level of customisation.
So, is Confluence damn good? No - there's a lot that could be improved. But from the mediocre solutions on the market today, it is one of the better choices.
You would not believe how special some use-cases are, especially when you work with organisations that have highly regulated environments. I've seen anything from markdown files in a git repository being semiautomatically created in a Jenkins run to an organization having built essentially their own wiki software because nothing on the market fulfilled their need at the time (now 5 years later, they realise no-one uses that thing because it is just unintuitive). I have seen organisations that have no content oversight and some who had a whole department of "content czars", whose sole job it was to keep their documentation fresh and updated. I've seen organisations that had strict rules on approving each individual change, with complex approval workflows.
If you have never documented anything, Confluence may be overwhelming, but so will every tool that has "sensible defaults", because before too long, you will start hitting the envelope. Documentation software is not like a MacBook that you just buy and start using, you always need some level of customisation.
So, is Confluence damn good? No - there's a lot that could be improved. But from the mediocre solutions on the market today, it is one of the better choices.
The lowest friction is not doing any documentation
Agreed, we use Confluence and use an agreed upon structure. It works fine from what I've experienced.
Can you share your structure? Or do you know any good open-source ones?
I personally have never seen it work, but of course I've also only seen a handful of data points.
I personally have never seen it work, but of course I've also only seen a handful of data points.
Best advice I can think of, avoid more than three indentations in the outline.
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 _________ as the tool for ticketing, documentation, etc not because it was good at ______, or _______ but because it fulfilled their action plan to have something, anything in place so that if the universe goes supernova, well some stuff was written down.
In my journey it seems that nobody is willing to criticize Edward Teach for the lousy treasure map he left, but rather we make fun of those who're still looking for his stuff.
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 _________ as the tool for ticketing, documentation, etc not because it was good at ______, or _______ but because it fulfilled their action plan to have something, anything in place so that if the universe goes supernova, well some stuff was written down.
In my journey it seems that nobody is willing to criticize Edward Teach for the lousy treasure map he left, but rather we make fun of those who're still looking for his stuff.
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 make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc.
That's the average wiki. It's a commons and a tragic one. To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc.
> To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc.
Maybe true in large orgs.
But for smaller companies what I've seen is usually paralysis.
e.g. someone notes a problem (maybe just a typo) in the doc. Can they fix it within seconds? If instead they need to raise a ticket then most likely it ain't happening. They move on, and the next person experiences the same problem.
IMO the default should indeed be towards everyone committing at will. Yes that will result in the occasional snafu. Fix that when it happens. (obviously not good practice for the operating manual for a nuclear power plant - but for a <500 person Saas company it is).
Maybe true in large orgs.
But for smaller companies what I've seen is usually paralysis.
e.g. someone notes a problem (maybe just a typo) in the doc. Can they fix it within seconds? If instead they need to raise a ticket then most likely it ain't happening. They move on, and the next person experiences the same problem.
IMO the default should indeed be towards everyone committing at will. Yes that will result in the occasional snafu. Fix that when it happens. (obviously not good practice for the operating manual for a nuclear power plant - but for a <500 person Saas company it is).
Ticket, or pull request?
Mandating a Jira ticket for simple typo fixes is overkill. But if you make it easy to create a PR directly on the documentation file, without leaving the tab, I don't see an issue. This is already a Github feature.
Mandating a Jira ticket for simple typo fixes is overkill. But if you make it easy to create a PR directly on the documentation file, without leaving the tab, I don't see an issue. This is already a Github feature.
We did PR's on documentation files at my last place, it worked but it was more painful than getting reviews for code PR's. Tickets work because they can be reasoned about, shoved aside, brought back into the limelight, updated, other tickets can easily be related to them as more information is discovered, etc.
Overall the comments on this page fall into 2 camps, people who've tried it all and found what works is discipline and those who are still trying it all.
Overall the comments on this page fall into 2 camps, people who've tried it all and found what works is discipline and those who are still trying it all.
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 when it comes to naming, formatting, audience, etc. I'm a huge fan of markdown/plain-text solutions, only because linters can be run that force you down one happy path. I don't believe Confluence has linters at all.
The default for Confluence is just that, everyone commits at will. There is no structure, tons of duplication, no standards when it comes to naming, formatting, audience, etc. I'm a huge fan of markdown/plain-text solutions, only because linters can be run that force you down one happy path. I don't believe Confluence has linters at all.
> 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 (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.
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.
Yes, handoffs have overhead and create process waste. They are a process smell and should be investigated for ROI.
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.
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.
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.
Internal documentation is everyone's responsibility, not a "tech writer". External should be written by a professional, agree.
"Everyone's responsibility" sounds like an euphemism for "no one really cares". When people actually care about something, they hire an expert.
Why do you hire software developers, instead of making software development everyone's responsibility? Is that because most people suck at software development? Well, most people suck at writing documentation, too.
Why do you hire software developers, instead of making software development everyone's responsibility? Is that because most people suck at software development? Well, most people suck at writing documentation, too.
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.
Well there is (ftr I dislike confluence, but come on) https://marketplace.atlassian.com/apps/1216387/approvals-for...
Interesting but is it really used? Less than 1000 installs for a product as popular as Confluence?
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.
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.
Ha I hear this a lot but the alternatives I have seen used are frankly just as terrible. I much prefer Confluence to a hidden web of Google docs.
Google Drive, the ultimate information black hole. Anything that gets sufficiently close will be sucked in and never seen again.
For my team we’ve switched to using GitHub markdown files with flowcharts: located within the folder containing the subsystem it describes.
Confluence is garbage
I'd take confluence over google docs because of how bad Google Docs' search is surprisingly
Oh yeah it's not great either I agree. But the use case for Google Docs is somewhat different in my mind. It's good for collaboration and discussion, rather than a source of truth to describe "how things are right now". It's annoying if you can't find a particular document immediately but it's not the end of the world. Discussion on a Google Doc will happen for a few weeks or a quarter, then die down and the doc will seldom be looked at again. You might link to it from tricky parts of your codebase but it's not essential to a high-level understanding.
Confluence and other wiki systems are clearly meant for longer-lived documentation and canonical information. You should link from or attach your working documents (spreadsheets, slide decks etc) to your wiki documentation for people to discover why certain decisions were taken. But if the wiki's discoverability is poor or it's not well-maintained or regularly reviewed, it's basically useless.
Confluence and other wiki systems are clearly meant for longer-lived documentation and canonical information. You should link from or attach your working documents (spreadsheets, slide decks etc) to your wiki documentation for people to discover why certain decisions were taken. But if the wiki's discoverability is poor or it's not well-maintained or regularly reviewed, it's basically useless.
Interesting. Not that long ago we moved everything out of Confluence into Google Drive because GD search worked. Confluence search was horrible to find docs I knew were there.
Confluence’s search is so bad, it might as well be a Write Once, Read Never tool.
That's because no-one bothers to read the documentation linked in the search field.
Protip: Use wildcards extensively. Differently from Google, Confluence search considers keywords entered to be limited by word delimiters. so foo matches only foo, not barfoo or footer. Use them with some wildcards, foo, and the search results starts to make sense.
Protip: Use wildcards extensively. Differently from Google, Confluence search considers keywords entered to be limited by word delimiters. so foo matches only foo, not barfoo or footer. Use them with some wildcards, foo, and the search results starts to make sense.
Do you mean searching within a document, or searching with google drive? I've found that google drive search is incredible, they've done a great job of indexing everything.
They have no content excerpts in search results, so it doesn't provide any help for finding which result is the one you want.
It also weights titles incredibly heavy, which combined with the previous part led to me not even noticing it searched the document body for years.
It also weights titles incredibly heavy, which combined with the previous part led to me not even noticing it searched the document body for years.
Not a fan of Google docs either, but I recently discovered CloudSearch which imo does a better job at searching Drive (and searches emails too, and few other places).
link: https://cloudsearch.google.com
link: https://cloudsearch.google.com
We use Mark[1] to automatically create Confluence pages from Markdown documents in our git repos. So we can have a review process for documentation changes, the documentation of the code can be in the repo with the code, and yet it can still be accessed without having to give permissions to view the code repo! Helpful with a proprietary monorepo.
[1] https://github.com/kovetskiy/mark
[1] https://github.com/kovetskiy/mark
So simple an idea, it makes you wonder why it's not already a core feature in Confluence.
Bitbucket wikis basically do this.
Yeah, the search function in my company's confluence is abysmal.
There have been times I know a page exists and I even know the title/content of the page and yet still I am unable to find it via the search.
There have been times I know a page exists and I even know the title/content of the page and yet still I am unable to find it via the search.
> 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.
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.
Did I miss it or does the article specify what tools Tremendous uses for their documentation?
Yeah, I push back when people say "can you document that API you wrote in confluence?"
It is such a stupid idea that it makes me question leadership.
Some things are good to document there, but generally, if you're documenting code, you should do it in the code.
It is such a stupid idea that it makes me question leadership.
Some things are good to document there, but generally, if you're documenting code, you should do it in the code.
So which tool do you like?
I will say the obvious: documentation sucks because good writing is a highly skilled activity that takes a lot of energy for most people to do, AND because keeping it up to date takes a lot of time, no matter how good you are at it, AND because leaders of companies don't want to spend ANY money on tech writers.
That's it. No mystery.
(BTW, this would also be why company financial records would suck, if management decided to save money on accounting staff and have all employees just kinda do their own accounting for the company. I SAY HIRE A SCRIBE FOR EVERY TECHNICAL TEAM!)
That's it. No mystery.
(BTW, this would also be why company financial records would suck, if management decided to save money on accounting staff and have all employees just kinda do their own accounting for the company. I SAY HIRE A SCRIBE FOR EVERY TECHNICAL TEAM!)
> good writing is a highly skilled activity
This. Yes, having everything written down and searchable is definitely a good goal. However, in my experience, the people in most companies have very different skills and few are good writers. So it probably takes a lot of time to create an organization that has a good process for creating great documents, let alone to transform an existing organization which can do so.
This. Yes, having everything written down and searchable is definitely a good goal. However, in my experience, the people in most companies have very different skills and few are good writers. So it probably takes a lot of time to create an organization that has a good process for creating great documents, let alone to transform an existing organization which can do so.
Ironically, it is much easier for me to write good documentation if there are a couple of meetings scheduled around it. Having 3 joint sessions with at least another person is great, first to get the "bone structure" of the document, then to confirm that the "flesh sits right", and finally to resolve any unclarities that might be left.
It sounds like you're describing something very similar to pairing (to write) and peer review on code, but for docs, rather than "meetings"?
I think it's important to realize that a lot of documentation is duplication. It duplicates something expressed in code, in configs, in structure, in people's heads, or in the real world.
Duplication can be useful. But the more of it you have, the greater the maintenance burden is. (The main exception is documentation that is not supposed to be kept up to date, like a daily journal or blog posts.) So I think it behooves people to be very careful about adding documentation. Because as you say, it can turn 1 problem into n problems.
Duplication can be useful. But the more of it you have, the greater the maintenance burden is. (The main exception is documentation that is not supposed to be kept up to date, like a daily journal or blog posts.) So I think it behooves people to be very careful about adding documentation. Because as you say, it can turn 1 problem into n problems.
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.
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.
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 think most of us approach documentation without intention. We write to express the idea, but fail to consider how the documentation fits into the deliverable.
For example, one could structure things where the English documentation is the deliverable. The code merely serves to actualize the document. In this world, we would consider the act of writing documentation of paramout importance, whereas the code is an implementation detail.
I think software as a discipline is distinctly undiscipled about these sorts of concepts.
For example, one could structure things where the English documentation is the deliverable. The code merely serves to actualize the document. In this world, we would consider the act of writing documentation of paramout importance, whereas the code is an implementation detail.
I think software as a discipline is distinctly undiscipled about these sorts of concepts.
Code is more complex than documentation specifically because it needs to deal with every issue. If you're going to cover every edge case in documentation, just write the code. Tools like OpenAPI/Swagger blur the lines.
Documentation is useful when it's job is to help understand why the code is the way it is, what problems are trying to be solved, and what constraints the devs had.
Documentation is useful when it's job is to help understand why the code is the way it is, what problems are trying to be solved, and what constraints the devs had.
Sure. But where some see the lack of updates as some sort of moral failure, I think it's usually a sign that there is a process problem. The documentation was supposed to solve some sort of problem, but the fact that people don't update it is usually a sign that either it wasn't a real problem, that documentation wasn't the right solution, or that there's a broken feedback loop in the team's process.
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.
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.
I am familiar with the notion that programmers are people who turn documents into code. I just think it's rarely true and even more rarely necessary.
Personally, I don't think documents have intent. People have intent. Sometimes they write down some words as an approximate way to communicate their intent in that moment. But if there is a conflict between the written document and the actual intent, it's the human intent that matters.
I also think that drift between written description and actual intent is good and desirable, because it usually means that the humans learned something about what actually needs to happen. So to the extent that documentation acts as leg irons for intent, I'm generally opposed to it. The faster our teams learn, the better the things we make.
Personally, I don't think documents have intent. People have intent. Sometimes they write down some words as an approximate way to communicate their intent in that moment. But if there is a conflict between the written document and the actual intent, it's the human intent that matters.
I also think that drift between written description and actual intent is good and desirable, because it usually means that the humans learned something about what actually needs to happen. So to the extent that documentation acts as leg irons for intent, I'm generally opposed to it. The faster our teams learn, the better the things we make.
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 confusion or request for more information within the company, I copy-pasta the relevant note from my obsidian bank to whomever person or whichever confluence page they deem the source of truth.
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 confusion or request for more information within the company, I copy-pasta the relevant note from my obsidian bank to whomever person or whichever confluence page they deem the source of truth.
Do you have any tips on how to maintain a developer's own knowledge base in Obsidian? I also use Obsidian but I currently use as more of a dumping ground.
It's actually quite simple even without using some of the advanced features: What I do is create a directory structure for each domain as I explore them. I.e.
Toplevel: - Work -- Job A: -- Daily notes -- Services -- Auth --- overview --- login flow -- Client -- Logger -- Job B: -- Daily notes -- Architecture -- node -- react -- etc
(edit: sorry about the formatting)
As the scope of your work expands, you add another sub-directory or file where necessary. Once it starts to grow in size, you can start making insightful connections via [[keyword]].
Furthermore, you can pretty much take this knowledge base with you, wherever you go, by uploading the vault file to your google drive and accessing it locally via SMB. Automatic save/backup.
Toplevel: - Work -- Job A: -- Daily notes -- Services -- Auth --- overview --- login flow -- Client -- Logger -- Job B: -- Daily notes -- Architecture -- node -- react -- etc
(edit: sorry about the formatting)
As the scope of your work expands, you add another sub-directory or file where necessary. Once it starts to grow in size, you can start making insightful connections via [[keyword]].
Furthermore, you can pretty much take this knowledge base with you, wherever you go, by uploading the vault file to your google drive and accessing it locally via SMB. Automatic save/backup.
I do the same except in org mode. I’ll export to markdown as needed but generally publishing documents is a secondary goal to empowering and decreasing the burden on myself.
Design docs for each and every feature has turned out not to scale for my current team. Larger, multi team features demand consolidated documentation, but for internal changes we rely on quick meetings as code reviews. Part of me misses the ceremony of the round table discussions, but the real difficulty is keeping track of why changes happen. Documenting processes and cross cutting concerns is a must have, but keeping track of all changes across quickly moving teams… it’s no surprise so many teams are just rife with tribal knowledge.
Design docs for each and every feature has turned out not to scale for my current team. Larger, multi team features demand consolidated documentation, but for internal changes we rely on quick meetings as code reviews. Part of me misses the ceremony of the round table discussions, but the real difficulty is keeping track of why changes happen. Documenting processes and cross cutting concerns is a must have, but keeping track of all changes across quickly moving teams… it’s no surprise so many teams are just rife with tribal knowledge.
So you are now the gatekeeper?
If an individual employee is going to put all that work in without being asked to or being given scheduled time to work on it they should get something in return.
Unless they were asked for, no? You aren't a snowflake and you aren't own praise for something you weren't asked to do. Maybe you work is great and valued (gold star), but your point of being owed something is just a bald face lie to yourself.
In the above scenario, I do not understand what they are getting in return.
Are you saying this person should be hired/paid to store and retrieve the information being sought out?
Are you saying this person should be hired/paid to store and retrieve the information being sought out?
Being as you put it the "gatekeeper" advertises their importance to everyone in the company who needs to know about the processes, making advancement easier and guarding against anyone thinking they are not necessary.
Maybe more like the font of knowledge?
What many dont realize is that documentation is tech debt. You can spend a lot of time and write a lot of documentation and have to also spend time updating it.
I have worked with teams that focus so much time on design docs and insist that everything has to be documented. Pace of work is slow. Documentation and designs became obsolete due to shutting down of services, change in architecture, refactors.
The best form of documentation is code.
I have worked with teams that focus so much time on design docs and insist that everything has to be documented. Pace of work is slow. Documentation and designs became obsolete due to shutting down of services, change in architecture, refactors.
The best form of documentation is code.
I think it’s a bit odd to call it tech debt. I’d say something more like “documentation is part of your tech, and needs to be maintained like the rest of your tech.” It’s only tech debt if you decide to not maintain it.
Agreed. Documentation has upkeep costs as the software and environment change.
> The best form of documentation is code.
Documentation as code might be a good alternative path, using the same tools and processes as software development and embed documentation tasks into engineering workflows. More insights in https://about.gitlab.com/blog/2022/10/12/five-fast-facts-abo... how the GitLab technical writing team collaborates.
Note: GitLab team member here.
Documentation as code might be a good alternative path, using the same tools and processes as software development and embed documentation tasks into engineering workflows. More insights in https://about.gitlab.com/blog/2022/10/12/five-fast-facts-abo... how the GitLab technical writing team collaborates.
Note: GitLab team member here.
Yeah, that sounds horrible yet familiar. Regarding this part:
> Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github.
When I'm the person being asked and know of the doc in question, here's what I try to do instead: I ask where someone searched for it. Then I update that place to refer to the correct document (and do some light refresh on the doc as needed). This works whether or not they tried to look before asking. If they did, well, now the next person who does that will just find it. If they didn't, I'm making them look before getting an answer. Maybe they find it, maybe they don't, either way I'll help them in the end if they're willing to look.
> Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github.
When I'm the person being asked and know of the doc in question, here's what I try to do instead: I ask where someone searched for it. Then I update that place to refer to the correct document (and do some light refresh on the doc as needed). This works whether or not they tried to look before asking. If they did, well, now the next person who does that will just find it. If they didn't, I'm making them look before getting an answer. Maybe they find it, maybe they don't, either way I'll help them in the end if they're willing to look.
You really have to be religious about enforcing a single source of truth for any information and this gets a lot better.
There are docs and then there are Docs. I think documents should be treated as source code. Go through a proper PR process so that you know what the latest and greatest is. Maintaining a wiki is one of the worst ways to document. It just creates a sprawl that is hard to control. I deal with it on a daily basis but have had little success with getting my team moving to our source control system for documents.
[deleted]
It's actually hilarious how Google - a company famous for it's search engine - made Docs, who's search function cannot find anything.
I live and breathe using Google Docs search functionality. It's my main way of finding files scattered across 10 years of folder hierarchies. It works great.
What do you mean it can't find anything?
What do you mean it can't find anything?
What I find is that it's very "dumb", almost "... WHERE filename LIKE '%query%'" dumb. Example might be searching for "<Cool Project> Technical Spec".
- Can't find "Technical Specification" in the "<Cool Project>" folder.
- Can't find "Tech Spec" (and vice versa)
- Can't find "<CoolProject>"
Is there some "enable real search functionality" checkbox I've missed, or am I just doing it wrong?
- Can't find "Technical Specification" in the "<Cool Project>" folder.
- Can't find "Tech Spec" (and vice versa)
- Can't find "<CoolProject>"
Is there some "enable real search functionality" checkbox I've missed, or am I just doing it wrong?
Yeah, I think you're "doing it wrong" as much as I hate to say that, sorry.
Search is keyword-based, like large-scale search is pretty much anywhere. Expecting "specifications" to match "spec" is expecting too much, same as expecting half your search to match a folder and the other half to match a file the folder is in.
The main thing to keep in mind is that search is content-based, not just filename. So instead, search for key terms you think are in the file, as opposed to focusing on folders/filenames. Start with one or two, then modify or add as necessary to narrow down.
Search is keyword-based, like large-scale search is pretty much anywhere. Expecting "specifications" to match "spec" is expecting too much, same as expecting half your search to match a folder and the other half to match a file the folder is in.
The main thing to keep in mind is that search is content-based, not just filename. So instead, search for key terms you think are in the file, as opposed to focusing on folders/filenames. Start with one or two, then modify or add as necessary to narrow down.
So basically you have to search google docs like you used to search the web before google came along and revolutionized search?
[deleted]
> Expecting "specifications" to match "spec" is expecting too much
When I use Google to search the whole web, it DOES match. So how come it doesn't work when I search a small document?
When I use Google to search the whole web, it DOES match. So how come it doesn't work when I search a small document?
Are you using search feature in Drive? I've been using CloudSearch, which I heavily rely upon
And it’s still miles better than Confluence.
I work in medical devices so we have to write a lot of docs. But they all disappear in document management systems where you can't find anything if you don't already know where it is. Are there no document management systems that are actually useful?
Ask yourself how many document management systems are selected after rigorous tests of actual usage vs those selected after sales presentations and schmoozing. That should give you your answer.
And if that's ambiguous, then ask how often your company penalizes people for making the common but wrong choice versus the uncommon but wrong choice.
And if that's ambiguous, then ask how often your company penalizes people for making the common but wrong choice versus the uncommon but wrong choice.
This applies to pretty much all enterprise software. It’s rarely selected by or for the benefit of the actual users. Usually it’s selected for the benefit of management (for example reporting) or for friends of management.
A good secretary (or a bunch of them) and filing cabinets.
You may still not know how to find anything, but they will.
Like a lot of other things, this has suffered from computerization making it yet another small part of everyone's job (which also increases context switching, the amount of shit you need to know and keep track of, and generally makes jobs more stressful) rather than a specialty that's the main focus of a few workers.
The benefit (get to stop paying some employees) is easy to measure, while the harm is not.
You may still not know how to find anything, but they will.
Like a lot of other things, this has suffered from computerization making it yet another small part of everyone's job (which also increases context switching, the amount of shit you need to know and keep track of, and generally makes jobs more stressful) rather than a specialty that's the main focus of a few workers.
The benefit (get to stop paying some employees) is easy to measure, while the harm is not.
"Like a lot of other things, this has suffered from computerization making it yet another small part of everyone's job (which also increases context switching, the amount of shit you need to know and keep track of, and generally makes jobs more stressful) rather than a specialty that's the main focus of a few workers."
Nicely said. I am getting really stressed out how complex things are becoming. It's already hard to keep up with git, Jira, Bitbucket, AWS, k8s, Helm, JS frameworks, databases and whatsoever. But then add hard to use document management systems and f...ed up processes that are mainly designed for management to get nice reports and not for productivity. Now you are a bad developer and you are a bad document management person because it's simply impossible to be good at all this stuff.
I am constantly preaching to management that we need specialized tech writers and specialized devs that are good at their respective. But I guess it looks cheaper to waste time and energy of engineers on stuff they aren't good at.
Nicely said. I am getting really stressed out how complex things are becoming. It's already hard to keep up with git, Jira, Bitbucket, AWS, k8s, Helm, JS frameworks, databases and whatsoever. But then add hard to use document management systems and f...ed up processes that are mainly designed for management to get nice reports and not for productivity. Now you are a bad developer and you are a bad document management person because it's simply impossible to be good at all this stuff.
I am constantly preaching to management that we need specialized tech writers and specialized devs that are good at their respective. But I guess it looks cheaper to waste time and energy of engineers on stuff they aren't good at.
git works for us across business/electronics/electrical/mechanical/software.
The exception is daily supply chain and accounting, which due to factors like urgency, multiple stakeholders per order, high pace of handover, external system integration, multilingual presentation requirements and nontechnical users we prefer a dedicated web based system with more of a real time focus with event hooks (eg. notification, translation, verification).
The exception is daily supply chain and accounting, which due to factors like urgency, multiple stakeholders per order, high pace of handover, external system integration, multilingual presentation requirements and nontechnical users we prefer a dedicated web based system with more of a real time focus with event hooks (eg. notification, translation, verification).
What kind of docs do you have in git? Git doesn’t work well with binary file formats like Word, Excel or Visio. You can do it but the diff won’t work.
Markdown + .webp, mostly. Some 'TeX.
Sometimes (often?) an outdated document is still great and useful and much better than no documentation at all
Equally often it’s worse and a waste of time. And you won’t know which world you’re living in for a while.
I've yet to find an outdated doc that makes the situation worse (unless you assume it's correct and up-to-date, which you should never do with anything anyway). There's a reason we like RFCs even if they only represent a decision in time.
Everyone wants accurate updated documentation.
Nobody knows how to accomplish this.
Whatever the solution is, if one exists, I'm sure it involves a lot of work keeping documentation up to date.
Nobody knows how to accomplish this.
Whatever the solution is, if one exists, I'm sure it involves a lot of work keeping documentation up to date.
They know how (documentation is embedded in/generated from code) they just don’t want to.
Out of date doc is worse than no doc, because it makes you feel all warm and fuzzy right until you footgun.
Out of date doc is worse than no doc, because it makes you feel all warm and fuzzy right until you footgun.
> 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.
How is this not inevitable if your goal is to always write things down? It seems like the way for document to be accurate is to keep the scope small and if you want everything in scope then it's going to contain a lot of outdated information.
How is this not inevitable if your goal is to always write things down? It seems like the way for document to be accurate is to keep the scope small and if you want everything in scope then it's going to contain a lot of outdated information.
You basically need to deprecate and eventually probably take offline outdated docs. There's something to be said for the historical record but if it's indexed--and if it's not no one will probably find it--it's going to compete with current documentation for search.
There's no easy answer.
There's no easy answer.
Large organizations in many sectors employ professional records managers for this reason (and many others). Every record has a “lifecycle” and it is deprecated and discarded after that.
So update the documents?
I mean, you're clearly not describing a high documentation culture, you're describing a culture that underinvests in intra-organizational communication.
I run a high documentation, low meeting culture by necessity (we operate in five time zones around world). Meetings vs docs is remarkably similar to the decision between paying for office space vs paying for occasional team retreats. If you run a fully remote company retreats are almost always a better use of your money than leasing office space. But you still need to pay for something.
Similarly with meetings vs. process documentation. If you're heavily remote and spread out I'd say you should cut down on meetings and being high documentation is the better choice. But again you still need to "pay" for something - you save time on meetings but you need to reinvest at least part of that time into writing documents.
Another bonus of documents is that they scale better than meetings. McDonald's doesn't deliver the same big Mac in every corner of the world by holding a lot of meetings. They have a book that goes out to all of their thousands of franchisees. When they want to add another thousand franchisees, they print more books.
If the documents are out of date my answer to my team is always "update them!" Anywhere that we're writing documents there are revision and discussion features so it's not like you can irrevocably screw something up, just improve it and let us know what you did. I do struggle with getting people to actually do it though.
I mean, you're clearly not describing a high documentation culture, you're describing a culture that underinvests in intra-organizational communication.
I run a high documentation, low meeting culture by necessity (we operate in five time zones around world). Meetings vs docs is remarkably similar to the decision between paying for office space vs paying for occasional team retreats. If you run a fully remote company retreats are almost always a better use of your money than leasing office space. But you still need to pay for something.
Similarly with meetings vs. process documentation. If you're heavily remote and spread out I'd say you should cut down on meetings and being high documentation is the better choice. But again you still need to "pay" for something - you save time on meetings but you need to reinvest at least part of that time into writing documents.
Another bonus of documents is that they scale better than meetings. McDonald's doesn't deliver the same big Mac in every corner of the world by holding a lot of meetings. They have a book that goes out to all of their thousands of franchisees. When they want to add another thousand franchisees, they print more books.
If the documents are out of date my answer to my team is always "update them!" Anywhere that we're writing documents there are revision and discussion features so it's not like you can irrevocably screw something up, just improve it and let us know what you did. I do struggle with getting people to actually do it though.
Having multiple systems for docs and Slack for follow-up questions is a major red flag. What you’re describing is a billion dollar search product opportunity though. Most orgs don’t have the discipline to have a single source of truth. So you end up with this mess. Run! Or … fix it and then create a company to fix it for all the other orgs with similar data/docs siloes.
I don’t understand why more companies don’t just go all in on Slack as the interface to their knowledge base. There’s tons of integrations to enable it. Every place I’ve worked at with Slack has the standard 90 day retention policy in place which makes it impossible.
One solution to this is to become an oracle at your company. Any time someone (namely someone higher in the company who is responsible for your pay) has a question, no matter how many times it's been asked, how recently it's been asked, how obvious and repeated it is in the documentation, you answer quickly and thoroughly, like a machine. After a year or two of this, you'll be able to ask for any raise, or to work remote, or to even switch to contracting. They won't want to lose you.
This is why I find documentation to be either useless or actively detrimental. Your documentation is the code. Unless you have a dedicated technical writer on the team whose full time job is to work with developers to document their code, it all just becomes an outdated confusing mess immediately.
Obviously this doesn't apply to public facing codebases. But trying to keep an internal codebase documented, other than fully finished self contained library level code, is a sisyphean task.
Obviously this doesn't apply to public facing codebases. But trying to keep an internal codebase documented, other than fully finished self contained library level code, is a sisyphean task.
Agree. If possible the documentation should live in / be generated from the code as well.
I'm not checking confluence, write it in a ".md" file in the repo if you want me to see it.
I'm not checking confluence, write it in a ".md" file in the repo if you want me to see it.
that's ok. but expect your onboarding to take a really long time.
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.
Exactly this.
I think that high documentation can work BUT the company has to invest in it in the way that Digital Ocean or even Stripe has done outwardly.
1. Investment - You have to hire at least a few technical writers and librarians to provide training & cleanup functions.
2. Management buy-in - You have to budget for it and encourage it through day one communication (ie. New hire training) and consistently rewarding and recognizing people for getting it right.
I think that high documentation can work BUT the company has to invest in it in the way that Digital Ocean or even Stripe has done outwardly.
1. Investment - You have to hire at least a few technical writers and librarians to provide training & cleanup functions.
2. Management buy-in - You have to budget for it and encourage it through day one communication (ie. New hire training) and consistently rewarding and recognizing people for getting it right.
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.
A lot comes from tribal knowledge/who to talk to/etc.
From my perspective, calling yourself a "high documentation" org leaves a similar impression as calling yourself a "high code" org.
Very much my experience too.
People need to actually learn how to write and maintain(!) documentation, otherwise it’s just a huge chaos.
Rule 1: less (text) is more.
People need to actually learn how to write and maintain(!) documentation, otherwise it’s just a huge chaos.
Rule 1: less (text) is more.
> 5 outdated documents describing the decision making process
Would that place be the U.S. Department of Defense by chance?
Would that place be the U.S. Department of Defense by chance?
> you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github
Are people at the same job telling you to check 3 different sources for internal docs? Maybe that is the main issue. Put knowledge in one place.
More specifically: One place that is not Sharepoint.
Are people at the same job telling you to check 3 different sources for internal docs? Maybe that is the main issue. Put knowledge in one place.
More specifically: One place that is not Sharepoint.
> no documents about how to actually use the resulting software.
Can all your engineers see all your other engineers' code? It's hard enough to get code to do what it says it does; I've very rarely seen documentation that's correct.
Can all your engineers see all your other engineers' code? It's hard enough to get code to do what it says it does; I've very rarely seen documentation that's correct.
Lack of organization to that degree is an indicator of failed leadership
This sounds so similar to my new place of employment, it has to be the same.
We might be colleagues then.
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 departments add, commit and push and then show maybe one person from each department how to solve conflicts. Alternatively, build non technical people a web interface for editing and committing but allow the devs to just use git as standard. Or there's Obsidian's built in sync but I don't know enough about it to know if it scales well in large organisations.
What absolutely is definitely not the solution is Confluence. I have not met anyone who has a positive thing to say about it. The only reason it is being so widely used is because it satisfies whoever is in charge of the finances because it comes bundled with Bitbucket and Jira.
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. Alternatively, build non technical people a web interface for editing and committing but allow the devs to just use git as standard. Or there's Obsidian's built in sync but I don't know enough about it to know if it scales well in large organisations.
What absolutely is definitely not the solution is Confluence. I have not met anyone who has a positive thing to say about it. The only reason it is being so widely used is because it satisfies whoever is in charge of the finances because it comes bundled with Bitbucket and Jira.
> 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.
Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people.
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.
Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people.
> 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 problem is.
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 problem is.
Or just download Github Desktop onto their machine and show them how to use it.
That's true. They should never be asked to touch the cli on this scenario.
> 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
Given the number of non-programmers who Really Need the functionality of git, who probably won't be able to hack dealing with it, doesn't this indicate that there's some huge vein of untapped value to be won by whomever cracks the problem? (Version control for business people?)
Given the number of non-programmers who Really Need the functionality of git, who probably won't be able to hack dealing with it, doesn't this indicate that there's some huge vein of untapped value to be won by whomever cracks the problem? (Version control for business people?)
I do get what you're saying because I struggled with it for ages. There are good GUI tools like Sublime Merge for easy conflict resolution now which would be one solution. I do think a web interface that just automatically commits by just adding your text in addition to the new text along with a warning would probably be the easiest solution and then just have someone edit it after the fact. It's not been my experience that there's a hell of a lot of merge conflicts going on with documentation anyway but I could see how it could happen if you had multiple non technical people actively working on a project.
Another not great but possible solution could be for non technical people to work on something like a Google Doc when stuff is in highly active development and to then copy this to a markdown document later when its solidified.
I do think that as a society we have to start looking at stuff like this as a new essential skill though. We wouldn't expect people to be working without basic literacy, numeracy and computer skills and I think we are going to have to start looking at upgrading our sense of what basic computer skills entails to include stuff like git and teaching it in schools from an early age.
Another not great but possible solution could be for non technical people to work on something like a Google Doc when stuff is in highly active development and to then copy this to a markdown document later when its solidified.
I do think that as a society we have to start looking at stuff like this as a new essential skill though. We wouldn't expect people to be working without basic literacy, numeracy and computer skills and I think we are going to have to start looking at upgrading our sense of what basic computer skills entails to include stuff like git and teaching it in schools from an early age.
I think even the idea of merging changes is a step too far for all but the most technical users. Most user's idea of what it should look like start and end at a word-like UI, so having to introduce the idea of merging different copies together and resolving conflicts is too far outside that view. In my opinion this is why Google docs has become popular because it solves that tricky problem of having to think about how your edits interact with someone else's.
Google docs works great but does require some discipline. There is always someone that starts working on a copy without telling anyone or switches to word/excel and local copies because they “need” feature x. Sometimes this is actually true, for example a legal document with esoteric numbering for headings. You’re going to buy a copy of word, not set out to explain the virtues of Google docs to your lawyer.
As much as I hate to admit it, sharepoint works better here.
On the upside for Google docs, commenting and edit suggestions work so well it’s become easier convince people to use Google docs without downloading copies.
As much as I hate to admit it, sharepoint works better here.
On the upside for Google docs, commenting and edit suggestions work so well it’s become easier convince people to use Google docs without downloading copies.
I do agree that an online google doc style WYSIWYG markdown solution would be preferable for non technical and then git and markdown for technical would be the ideal solution.
My sense is the markdown/git/render a documentation wiki with mkdocs is mostly solved. The issue is having that easy interface for non-tech folk.
And related to this is the state of WYSIWYG markdown editing.
The Basecamp folks created the very polished Trix rich-text drop-in which is a replacement for TinyMce, which while the standard seems to carry issues.
Basecamp explained the issue with most approaches as such:
> Most WYSIWYG editors are wrappers around HTML’s contenteditable and execCommand APIs, designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, and eventually reverse-engineered and copied by other browsers.
> Because these APIs were never fully specified or documented, and because WYSIWYG HTML editors are enormous in scope, each browser’s implementation has its own set of bugs and quirks, and JavaScript developers are left to resolve the inconsistencies.
> Trix sidesteps these inconsistencies by treating contenteditable as an I/O device: when input makes its way to the editor, Trix converts that input into an editing operation on its internal document model, then re-renders that document back into the editor. This gives Trix complete control over what happens after every keystroke, and avoids the need to use execCommand at all.
Unfortunately Trix does not render markdown so can’t be used in a markdown documentation workflow.
Has anyone seen a decent implementation of WYSIWYG for markdown that has the necessary polish to be non-tech friendly?
And related to this is the state of WYSIWYG markdown editing.
The Basecamp folks created the very polished Trix rich-text drop-in which is a replacement for TinyMce, which while the standard seems to carry issues.
Basecamp explained the issue with most approaches as such:
> Most WYSIWYG editors are wrappers around HTML’s contenteditable and execCommand APIs, designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, and eventually reverse-engineered and copied by other browsers.
> Because these APIs were never fully specified or documented, and because WYSIWYG HTML editors are enormous in scope, each browser’s implementation has its own set of bugs and quirks, and JavaScript developers are left to resolve the inconsistencies.
> Trix sidesteps these inconsistencies by treating contenteditable as an I/O device: when input makes its way to the editor, Trix converts that input into an editing operation on its internal document model, then re-renders that document back into the editor. This gives Trix complete control over what happens after every keystroke, and avoids the need to use execCommand at all.
Unfortunately Trix does not render markdown so can’t be used in a markdown documentation workflow.
Has anyone seen a decent implementation of WYSIWYG for markdown that has the necessary polish to be non-tech friendly?
I believe Obsidian are using ProseMirror or CodeMirror, the logo is at the bottom of CodeMirror so I assume it is the latter. There was this forum post from one of the Obsidian team a few years back asking about it
https://discuss.codemirror.net/t/implementing-wysiwyg-markdo...
https://codemirror.net
https://prosemirror.net
https://discuss.codemirror.net/t/implementing-wysiwyg-markdo...
https://codemirror.net
https://prosemirror.net
This would be worth checking out, which shows how CKEditor implements markdown editing:
https://onlinemarkdowneditor.dev/
Yes, CKEditor accepts Markdown input thanks to a customizable autoformatting feature: https://ckeditor.com/docs/ckeditor5/latest/features/autoform...
This allows users to employ all the familiar shortcodes on the go. It's basically the user's choice whether to type in Markdown or use the rich-text formatting buttons.
Additionally, it's possible to switch the default CKEditor 5 output from HTML to Markdown: https://ckeditor.com/docs/ckeditor5/latest/features/markdown...
I'm technical and I still prefer WYSIWYG for writing documents. I want it to be easy for me to pull in rich content (images, info boxes, column formatting)
It's ok to be technical and not enjoy markdown, heh.
It's ok to be technical and not enjoy markdown, heh.
GitHub does offer the ability to modify files within the web UI and open a PR from there.
GitHub wikis or something similar can work well as an in-between option: edit in browser or git clone, whichever is easier in your context.
https://github.blog/2011-01-17-git-powered-wikis-improved/
https://github.blog/2011-01-17-git-powered-wikis-improved/
[deleted]
> Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people.
How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?
How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?
Most of the issues with Confluence I've seen are lack of organisation, out of date information mixed with up to date pages and really poor search / discoverability. The fact that people can just edit or create a page at any point is one of the better parts because it's easy for someone to fix something up during onboarding, during a drive-by consultation etc.
Even poor discoverability can be fixed with labels.
But yes, the out of date info is a killer.
But yes, the out of date info is a killer.
There are Wiki-like interfaces for git+Markdown: GitHub's wikis, gitit, and more.
Google Docs
The Google Docs/Sheets version history strikes a pretty good balance of friendliness and power. The biggest weakness I've seen with it in the hands of non-technical users is that they don't know it's there.
In fact you lost non-technical people at Markdown.
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, you might have a hope of teaching them HTML. Today? No chance. In particular I think "willingness to learn anything" has really waned.
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, you might have a hope of teaching them HTML. Today? No chance. In particular I think "willingness to learn anything" has really waned.
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).
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).
Definitely. My thought is rather that it’s an additional point of friction that makes selling a workflow like this more difficult.
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.
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.
Thanks for sharing! Do you mind describing more technical details about the rendering pipeline for docs that you use?
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 vacation half the time to render the latest docs.
When it comes to API documentation, everything should just be inline comments in the doc format of choice for the team. Don't bother rendering this out, because every flipping tool ever invented for converting inline documentation into HTML fails on something simple. Developers can read the inline docs as-is and/or rely on their IDE to provide them hints from those docs.
If you have to deploy your documentation, that's how you know you might as well give up. It's one thing to deploy documentation for 3rd parties, but for documentation being used internally there's few good reasons to turn the documentation into its own website. That's extra work that I've never seen increase productivity or developer happiness. Don't put documentation behind one or two guys with special permissions to press a deploy button. If you do, the documentation will always be out of date as soon as it's rendered.
Remove as many reasons that devs won't write documentation as you possibly can.
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 vacation half the time to render the latest docs.
When it comes to API documentation, everything should just be inline comments in the doc format of choice for the team. Don't bother rendering this out, because every flipping tool ever invented for converting inline documentation into HTML fails on something simple. Developers can read the inline docs as-is and/or rely on their IDE to provide them hints from those docs.
If you have to deploy your documentation, that's how you know you might as well give up. It's one thing to deploy documentation for 3rd parties, but for documentation being used internally there's few good reasons to turn the documentation into its own website. That's extra work that I've never seen increase productivity or developer happiness. Don't put documentation behind one or two guys with special permissions to press a deploy button. If you do, the documentation will always be out of date as soon as it's rendered.
Remove as many reasons that devs won't write documentation as you possibly can.
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
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!
I do think just using the folder of markdown folders is far preferable to browsing on the web wherever possible but there's definite use cases where it's unavoidable. I do think this is a very strong case for using Obsidian however, because you literally don't have to mess about with maintaining any kind of SSG, you just put `publish: true` in the metadata of whatever note you want publishing and then just click the Publish button and it's there on the website.
I don't like Confluence either, but the platform is only 10% of the problem. Knowledge Management platforms are something that PMs love to debate, purchase, and use to get promotions. So you end up with a company that has 6+ platforms. This is way worse than having one unified, crappy-UX, wiki.
Finding the perfect documentation platform becomes a waiting-for-superman game. Everyone loves to complain, but nobody wants to put in the actual work to write clear content, define information structure, consider audience, etc.
The real solution is hiring people who are excellent writers. To do this, leadership must be good at reading and writing themselves (not a given) and be able to recognize top contributors.
Finding the perfect documentation platform becomes a waiting-for-superman game. Everyone loves to complain, but nobody wants to put in the actual work to write clear content, define information structure, consider audience, etc.
The real solution is hiring people who are excellent writers. To do this, leadership must be good at reading and writing themselves (not a given) and be able to recognize top contributors.
That is indeed too technical. Try to explain how inserting an image is not just copy paste.
Make it copy-paste. Automatically upload it to the image blob storage and insert the image code, then show the WYSIWYG preview.
Sure, and then the question comes of why you have a separate editor and preview, and you finally end up with a WYSIWYG editor.
1. Paste image into assets folder.
2. Write .
It's not that hard really is it.
2. Write .
It's not that hard really is it.
Have you worked with non-technical teams, ever? Perhaps in teams of very young and gamer-type people this would work, but in any real world team I've been in, this would not in fact be easy unless there's a real time preview and a button you can click that auto-generates that snippet. People would forget the exclamation mark, mixup the brackets with the parenthesis, not know how to reference the right path to the image, and ask a developer to help them out.
Well presumably this would be less of an issue if you had easy to use, easy to search and easy to maintain documentation, you know, maybe in the form of markdown files with a search bar where you could type 'how to paste image into documentation' in case you forgot...
At the end of the day, if you've got someone who can't work out how to drag a file into a folder and then type  after you've shown them a couple of times, is this really the person you want writing the documentation for your process?
At the end of the day, if you've got someone who can't work out how to drag a file into a folder and then type  after you've shown them a couple of times, is this really the person you want writing the documentation for your process?
At the end of the day, if you've got someone that can't figure out there are people that are not good at technical things, do you really want them to develop your user facing software?
Ok mate we’ll all go back to living in huts because we decided we had to go at the pace of the slowest people in society.
If someone is confused by markdown syntax it is hard to imagine how they contribute professionally.
Maybe you should try to imagine a little harder. "If You Judge a Fish by Its Ability to Climb a Tree, It Will Live Its Whole Life Believing that It is Stupid"...or in this case you will live your whole life believing every non-technical person around you is stupid...which just sounds miserable for everyone involved.
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 unexpected arguments.
— 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 unexpected arguments.
She grew up with computing systems that had no concept of keyboard shortcuts and intentionally abstracted away the concept of the file system and documents.
I think her assessment of the situation is fair.
I think her assessment of the situation is fair.
My assessment is that she can’t work in an office.
They can’t belong on the side of the world where we make things. She’ll forever belong in the people we’ve designed our apps for, viewing videos, playing games, instagram models, struggling to afford a flat. Maybe we’ll make her rich! Our apps will decide that.
They can’t belong on the side of the world where we make things. She’ll forever belong in the people we’ve designed our apps for, viewing videos, playing games, instagram models, struggling to afford a flat. Maybe we’ll make her rich! Our apps will decide that.
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.
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 think you're lacking a lot of empathy for nontechnical users. I don't see how you could ever argue that your git + Obsidian stack is "more valuable" than an off-the-shelf wiki solution.
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 think you're lacking a lot of empathy for nontechnical users. I don't see how you could ever argue that your git + Obsidian stack is "more valuable" than an off-the-shelf wiki solution.
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?
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?
> 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.
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.
> 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.
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.
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.
> What issues do nontechnical people have with Confluence that are easier in just Markdown?
Your claim that I was responding to is that "everything Just Works" in Confluence, not that Markdown is easier. I have commented on neither Markdown nor their relative ease.
> The typical gripes are around search and organization, not editing.
That would seem to contradict both that everything Just Works and that you have never heard nenontechnical people complain about it.
Your claim that I was responding to is that "everything Just Works" in Confluence, not that Markdown is easier. I have commented on neither Markdown nor their relative ease.
> The typical gripes are around search and organization, not editing.
That would seem to contradict both that everything Just Works and that you have never heard nenontechnical people complain about it.
> I have commented on neither Markdown nor their relative ease.
Unfortunately, you've inserted yourself into a conversation where this is what we're talking about. If you want to talk about something else, maybe start your own thread.
The point of contention here is that Atlassian's wiki is far easier for nontechnical people to deal with than pure markdown and git. And yes, from their perspective, it Just Works. They never wrangle with syntax, there's a massive plugin ecosystem for custom features, and version history works out of the box.
Unfortunately, you've inserted yourself into a conversation where this is what we're talking about. If you want to talk about something else, maybe start your own thread.
The point of contention here is that Atlassian's wiki is far easier for nontechnical people to deal with than pure markdown and git. And yes, from their perspective, it Just Works. They never wrangle with syntax, there's a massive plugin ecosystem for custom features, and version history works out of the box.
> 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.
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.
> 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!
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!
> 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 anymore, you can't work around the WYSIWYG editor when it's broken. Uploading or converting to it from external sources is a PITA, when it's even possible.
If you want technical documentation that developers are going to maintain, it has to be a joy to work with in their own editors.
WYSIWYG isn't actually better. It's a broken paradigm, and that's why every single attempt to move Wikipedia over to a WYSIWYG editor has failed.
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 anymore, you can't work around the WYSIWYG editor when it's broken. Uploading or converting to it from external sources is a PITA, when it's even possible.
If you want technical documentation that developers are going to maintain, it has to be a joy to work with in their own editors.
WYSIWYG isn't actually better. It's a broken paradigm, and that's why every single attempt to move Wikipedia over to a WYSIWYG editor has failed.
> 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.
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.
"I want to insert an image." Whoops, you're already in deep trouble. "I want to resize it." Even worse!
These are table stakes features that everyone expects to work out of the box. If you don't give them a WSIWYG editor that does all of this for you automatically, it's DOA.
These are table stakes features that everyone expects to work out of the box. If you don't give them a WSIWYG editor that does all of this for you automatically, it's DOA.
You don't need WYSIWYG for dragging and dropping images into a document, or even for resizing them. WYSIWYG is an approach to layout and formatting, not the only alternative to writing LaTeX in a terminal-bound text editor.
You are probably arguing with another developer here. Imagine having this same discussion with some business person who uses MS Excel and Word all the time, and trying to convince them that your text only thing where you can't easily add a chart coming from Excel is better than what they are currently using.
Would love to see how that conversation goes.
Would love to see how that conversation goes.
I can already picture it: "Hey rcarr, how do you insert a picture again?" "With " "My image is not showing up!" "Let me take a look at it..., oh, it seems you mistyped the filename", "Oh yeah, sorry about that".
Welcome to the world of non-technical people.
Welcome to the world of non-technical people.
You cannot expect non-technical people to use git from the command line. I still like your idea though: the documentation can be based on markdown files in a git repository, but then you have to build or find a web-based WYSIWYG editor with Git support for non-technical folks. If you use GitHub already, it wouldn't actually be so bad to teach the non-technical folks to use the Git UI only to make documentation changes.
I find Dropbox to have much less friction (almost zero) compared to git. In the teams with nontechnical people it is often enough to just use Dropbox. Git requires manually committing, which is friction and people often forget to commit changes.
The fact you need one person technical enough to resolve conflicts is already a deal breaker.
The fact you need one person technical enough to resolve conflicts is already a deal breaker.
Well, you can actually just script that. Dropbox is fun, until you want previous versions.
At the place I worked for 22 years ago, we had an SMB fileshare for designers/front-end devs (html templates + templating lang), which would simply commit everything to CVS at night.
At the place I worked for 22 years ago, we had an SMB fileshare for designers/front-end devs (html templates + templating lang), which would simply commit everything to CVS at night.
Setup a service with Dropbox sdk and python to pull the data, commit them, and push (even forced) to git.
At least you will have multiple revisions.
At least you will have multiple revisions.
This sounds like a programmer's rather naive take to be honest.
Available PLM/PDMs could be improved a lot yes, but you're not gonna replace them by slapping a GUI on git (I mean, you could do that but it's really just a pretty small part of the problem space).
Available PLM/PDMs could be improved a lot yes, but you're not gonna replace them by slapping a GUI on git (I mean, you could do that but it's really just a pretty small part of the problem space).
> 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.
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.
This looks great, but no Android or mobile support outside iOS is a big negative
An easier one stop shop alternative is just Notion. Recommend it for the reason of having an internal wiki/documentation. Probably one of the only real use cases for Notion, everything else (like personal note taking or time organization) is horrible on it.
This was actually my next suggestion when Obsidian got shot down. It's definitely a nice half way house between the two. Again it got dismissed albeit this time with no explanation, I assume because the request for feedback and suggestions wasn't actually anything of the sort but basically a pretend exercise on behalf of management to 'show we're listening'.
[deleted]
This is what the Gitlab wiki does. There's a markdown+git interface for technical folks and a web interface for normal people.
It's what we use, and what I find the be the less annoying solution, but there are two big show-stoppers to make it more user-friendly:
- the default index on the sidebar doesn't handle sub-directories well (https://gitlab.com/gitlab-org/gitlab/-/issues/17673) - we use a pipeline to refresh an index page, but it's duct-tape and annoying to setup.
- can't edit only a section of a page, so if the page has a few sections, I often lose track of what exactly I wanted to change (maybe the WYSIWYG helps here, have to admit I have not used it much)
Otherwise I like that each project has its wiki, and so instead of one huge messy wiki, it's a few smaller messy wiki, easier to cleanup and have clear owners.
- the default index on the sidebar doesn't handle sub-directories well (https://gitlab.com/gitlab-org/gitlab/-/issues/17673) - we use a pipeline to refresh an index page, but it's duct-tape and annoying to setup.
- can't edit only a section of a page, so if the page has a few sections, I often lose track of what exactly I wanted to change (maybe the WYSIWYG helps here, have to admit I have not used it much)
Otherwise I like that each project has its wiki, and so instead of one huge messy wiki, it's a few smaller messy wiki, easier to cleanup and have clear owners.
I use Confluence pretty heavily at work (I write most of our docs) and I like it. Any annoying UI elements, I hide with ublock origin. I don't mind the lag, although I do wish it were faster.
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 not require granting a user access to a repo to write to a file. It has much more rich content to better convey information clearly to humans. It has full text search. Page management is simple (rename a page and it auto-redirects). And no other solution does all of this as easily or effectively.
The people who complain about Confluence simply don't care about use cases outside their own, and haven't taken the time to learn it. I am 100x more productive with Confluence than you are with Git and Markdown. And real people will actually be able to use what I've made there without learning complex tools or jumping through hoops.
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 not require granting a user access to a repo to write to a file. It has much more rich content to better convey information clearly to humans. It has full text search. Page management is simple (rename a page and it auto-redirects). And no other solution does all of this as easily or effectively.
The people who complain about Confluence simply don't care about use cases outside their own, and haven't taken the time to learn it. I am 100x more productive with Confluence than you are with Git and Markdown. And real people will actually be able to use what I've made there without learning complex tools or jumping through hoops.
I agree except I’ve been using Quip recently and it’s been a nice alternative to Confluence albeit similar.
> 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.
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.
Hadn't heard of this before, looks very cool. For anyone interested: https://github.com/claudioc/jingo
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.
Some people have built it. For example: https://www.macupdate.com/app/mac/49459/draft-control
You'd have a much easier time getting this adopted if you created a fancy GUI on top of the infra you just detailed out. Most people don't want to deal with git, no one wants to write in markdown all day, and the more obstacles you introduce to making documentation the less documentation gets made.
If the two options are confluence and sharepoint I choose confluence every time. Somehow people have decided that because sharepoint can do document store and html it's a kb. and because it comes with O365 exec's love it because its "free".
If the two options are confluence and sharepoint I choose confluence every time. Somehow people have decided that because sharepoint can do document store and html it's a kb. and because it comes with O365 exec's love it because its "free".
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 :) )
I always marvel at gitlabs handbook and would love to introduce it to our company. Are there any tutorials how to set it up? (I don't mean how to set up gitlab, but rather which tools you need and how to set up the render pipeline, server etc to enable a markdown wiki/handbook?
GitLab employee here. This page of our handbook can be a good starting point to build your own: https://about.gitlab.com/company/culture/all-remote/handbook...
I'll say a positive thing about Confluence from the point of view of a mars rover operator. We use it as our main reference on shift and it works great for us. We migrated from twiki and the fact that the search works, everybody can edit easily, and it has a bunch of useful integrations including draw.io . I do wish it had markup or html editing.
>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.
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.
Git is not that complicated and this may work for purely internal software docs. But good luck scaling your org, working with customers, investors, vendors etc and not ending up with at least done MS office documents and email as the only record of what is the latest version.
I couldn't disagree more, every ounce of friction that you add to the process of writing documentation is dozens if not hundreds of documents that could have been written and are not going to be.
Unless of course there's a good reason for maintaining your docs in markdown files, but all of them?
Unless of course there's a good reason for maintaining your docs in markdown files, but all of them?
[deleted]
confluence is ok, though I think I had problems with literal search: https://jira.atlassian.com/browse/CONFCLOUD-69222
What's the benefit of your solution? I mean git has excellent history lookup capabilities, but that's the only benefit I see. Maybe another one is that you can update documents without leaving cli..
What's the benefit of your solution? I mean git has excellent history lookup capabilities, but that's the only benefit I see. Maybe another one is that you can update documents without leaving cli..
For starters, the Confluence editor is absolutely dire. We can all stand here and sing til the cows come home about how it shouldn't be the world we live in, but the reality is that not a lot of people want to or have the time to write documentation so we should be making it as easy and fast as possible to do. As much friction as possible should be removed. It does not get a hell of a lot easier or quicker than writing a Markdown file.
Second, because it is plain text, search is blisteringly fast using any number of different tools. Following on from that for a third benefit: portability. You're not tied to any one service. You can use any text editor for editing and you can use a multitude of different solutions for publishing. Version control? Use whatever you what.
Another benefit: easy linking of files using [[wikilinks]] and block inclusion. If this is done properly, you can also use the graph view to get an oversight on how your code affects other parts of the codebase at a glance.
Second, because it is plain text, search is blisteringly fast using any number of different tools. Following on from that for a third benefit: portability. You're not tied to any one service. You can use any text editor for editing and you can use a multitude of different solutions for publishing. Version control? Use whatever you what.
Another benefit: easy linking of files using [[wikilinks]] and block inclusion. If this is done properly, you can also use the graph view to get an oversight on how your code affects other parts of the codebase at a glance.
I don't think documentation is a problem with a technical solution - it's an organizational commitment and incentives problem.
That just sounds like rebuilding Notion internally, and this is coming from someone who uses Obsidian locally and Notion company-wide.
notion lost appeal when I noticed that search doesn't work. E.g. I have a page with wireguard mentioned in text and I cannot find it when searching for wireguard.
yeah notion's search never seems to provide me with what i am actually looking for.
Saddling entire companies with having to learn git, even at a basic level, is a hilarious idea.
Ha yeah good luck with that, many people think confluence is too technical to use!
[deleted]
You talking about 'wiki'?
Moving to America from France, one of my biggest surprises was how poor the average engineer (person really, but engineers affect me directly at work) is at summarizing concepts clearly.
I learned a little later that "summary" exercises are not a thing taught in school here, which surprised me. In France, "le résumé" is an exercise that they constantly drill into students (particularly technical ones), in which you take a 3 page paper and condense it into 100 words. I really hated doing it back in the day, but as an adult I now am very grateful I did and wished other countries made this more prevalent.
I learned a little later that "summary" exercises are not a thing taught in school here, which surprised me. In France, "le résumé" is an exercise that they constantly drill into students (particularly technical ones), in which you take a 3 page paper and condense it into 100 words. I really hated doing it back in the day, but as an adult I now am very grateful I did and wished other countries made this more prevalent.
Teaching how to write summaries in the US would be a good idea. To make things even worse, in the US most essays are assigned a minimum length so students learn to pad their writing with lots of fluff and circumlocutions.
Purely anecdotal, but I recall plenty of summarizing assignments, along with other reading comprehension tasks in my English classes. Though you're right about the minimum length padding thing reinforcing the opposite skill.
I'm convinced there must be a prescribed US essay structure that mandates describing what you're going to discuss in the essay - it has been poorly translated into the style for youtube videos.
Yes, this is literally the case from grade school all the way into college level technical writing courses. The first paragraph, or first section depending on the length of the work, should essentially be a high level summary of the entire work. I remember in middle school we were also taught to write our paragraphs this way, that is, the first sentence should be a gestalt of the entire paragraph. The conclusion of each paragraph, and also the conclusory paragraph itself, is also supposed to have this behavior to some extent.
It took me quite a few years to realize how dry, boring, and repetitive this makes your writing, and I now choose to write as I talk. Might make for worse documentation, but it's far better for conversing with other people either in real time or in back-and-forths via email.
It took me quite a few years to realize how dry, boring, and repetitive this makes your writing, and I now choose to write as I talk. Might make for worse documentation, but it's far better for conversing with other people either in real time or in back-and-forths via email.
Say what you're going to say (briefly)
Say it (at length)
Say what you've said (briefly)
Is how you successfully present things in the US
Say it (at length)
Say what you've said (briefly)
Is how you successfully present things in the US
It’s probably part cultural as well because We teach the opposite. We encourage students to be verbose. Longer term papers are rewarded. Your graduate thesis? How about 100 pages.
We also encourage bullshitting in everyday communications. It drives me nuts.
We also encourage bullshitting in everyday communications. It drives me nuts.
Anecdotally, as someone who got a Master's in English and had to TA and tutor writing at a college level, it's the schools/universities. English departments are being defunded because Business degrees and Engineering degrees make the schools more money and are seen as more "valuable". So most people with a non-liberal arts degree from the states can barely write above a high school level. But it's good enough.
Very interesting perspective! I generally attributed that more to different proficiency levels in English as a second language, rather than language-independent summarization skill, but I guess that's also a realistic option.
We're taught to write book reports until about 6th grade and then we never revisit that skill again. :/
I had to do this for an undergraduate business degree here in the US and it feels like a super power working in software.
In America when we can’t explain something we print more money and redo the solution. Often creating more problems but that’s our flywheel we’re talking about!
Sounds like this works great for them, and an awesome environment to be a part of.
However I'd be very curious to see how this evolves as the company grows. Personally, I am skeptical that this is sustainable in the long term. In my experience, most people are a) bad at writing and b) hate reading. And as a company grows, and the number of documents that need to be written and read explodes, this work pattern eventually becomes untenable. More and more meetings get scheduled to cover topics that are not well documented, which causes people to have less time/inclination to create or consume high quality documents, and it becomes a feedback loop.
(Edited to make it clear that I am not against the idea, just curious to see how it evolves)
However I'd be very curious to see how this evolves as the company grows. Personally, I am skeptical that this is sustainable in the long term. In my experience, most people are a) bad at writing and b) hate reading. And as a company grows, and the number of documents that need to be written and read explodes, this work pattern eventually becomes untenable. More and more meetings get scheduled to cover topics that are not well documented, which causes people to have less time/inclination to create or consume high quality documents, and it becomes a feedback loop.
(Edited to make it clear that I am not against the idea, just curious to see how it evolves)
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 of their ideas. They hadn’t considered these things and now they feel out of their element.
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 of their ideas. They hadn’t considered these things and now they feel out of their element.
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 than anything else.
A dev who can articulate is literally worth at least 50% more than one who cannot.
And to your point, yes, it's funny and scary when someone can't describe something they ought to be able to.
If someone can't explain something they are actually a risk to the code.
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 than anything else.
A dev who can articulate is literally worth at least 50% more than one who cannot.
And to your point, yes, it's funny and scary when someone can't describe something they ought to be able to.
If someone can't explain something they are actually a risk to the code.
> 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.
It's organized for them, but not for others. This skill is not intuitive to learn, so it shouldn't be shocking.
I think if someone takes the effort to make information widely known and notice whether people understand it and adjust, they will make progress.
The real problem is that for those with authority, it seems to pay off that their disorganization affects other people. It makes others artificially reliant on them, which establishes their position even further, and there’s not really any consequences.
Imo, this is cheating at life and the authority someone gets from being disorganized isn’t real success. Real success comes from having true influence and respect from others due to helping them a lot. This is a lot more difficult though.
Oh well. All the people who rule molehills don’t stop anyone else from achieving real success, so they’re only holding themselves back at the end of the day.
The real problem is that for those with authority, it seems to pay off that their disorganization affects other people. It makes others artificially reliant on them, which establishes their position even further, and there’s not really any consequences.
Imo, this is cheating at life and the authority someone gets from being disorganized isn’t real success. Real success comes from having true influence and respect from others due to helping them a lot. This is a lot more difficult though.
Oh well. All the people who rule molehills don’t stop anyone else from achieving real success, so they’re only holding themselves back at the end of the day.
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).
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).
It's funny how AI and humans struggle with similar issues of doing things intuitively and being unable to explain themselves.
Yes! What's threatening about AI isn't that it's smarter than humans, but that it's cheaper and more scalable. And sometimes smarter. But usually a whole lot dumber.
You reminded me of a fun idea that I'll probably never do anything with:
Train an AI which is judged on its ability to quickly teach/train _another_ AI how to do the task. So, optimizing for ability to explain.
You reminded me of a fun idea that I'll probably never do anything with:
Train an AI which is judged on its ability to quickly teach/train _another_ AI how to do the task. So, optimizing for ability to explain.
Train an AI which is judged on its ability to train humans. I don't think we're ever going to really trust AI until it can explain itself clearly to humans. And that's pretty close to being able to teach.
I got to the point where I sign up to "people hate reading full stop".
It is not to blame anyone, because what people want in reality is answers and answers now - not searching through 20 pages of text, even if it is well written.
My tasks at work are not "read Anna Karenina and think about it". They are more "given X, Y and Z can you produce G and if yes, do so ASAP please".
Which takes us to the meetings and asking around which quite often is quickest way to get correct answer - even if answer is in a "well written down documentation".
Simple text search is not there yet, any advanced system for "knowledge management" fails really quickly in that regard because it takes effort to learn. It is either that setting up such knowledge management system takes too much time or getting used to it takes too much time.
This is why I cringe when I see knowledge management systems posted here on HN, usually these are cute toys but are not really solving anything unless their founders convince 90% of world population to meticulously fill in data in such system.
It is not to blame anyone, because what people want in reality is answers and answers now - not searching through 20 pages of text, even if it is well written.
My tasks at work are not "read Anna Karenina and think about it". They are more "given X, Y and Z can you produce G and if yes, do so ASAP please".
Which takes us to the meetings and asking around which quite often is quickest way to get correct answer - even if answer is in a "well written down documentation".
Simple text search is not there yet, any advanced system for "knowledge management" fails really quickly in that regard because it takes effort to learn. It is either that setting up such knowledge management system takes too much time or getting used to it takes too much time.
This is why I cringe when I see knowledge management systems posted here on HN, usually these are cute toys but are not really solving anything unless their founders convince 90% of world population to meticulously fill in data in such system.
It works if you hire for people who are good at communicating and reward documentation writing in performance reviews
hiring is probably the main thing. giving some kind of documentation exercise to all prospective devs seems to alleviate concerns about communication
Agree that hiring is sure important, but I think as long as hiring is competitive, and most candidates are bad at writing, then compromises are almost inevitable?
If FAANGs started putting more weight on technical-writing skills in their hiring, we would get Leetwriting and technical-writing bootcamps. Meaning, it’s just an education issue to some extent, and there’s currently too little motivation to train writing as a skill.
Leetcode doesn't raise people's IQs, it gives them practice effect on tech's favorite IQ test. So I don't think leetwriting would work for anything except getting practice effect on the new verbal IQ tests.
We already struggle finding people good at everything else lol
Most people are a) bad at listening and b) hate meetings, but that doesn't stop them...
No not to the same extent. Meetings proliferate because people love them. LOVE them. Programmers dislike them because of flow but everyone else can't get enough of them. I only realized after enough years outside the tech industry. Meetings are like eating junk food. They make people feel important and like they had a busy/productive day, even if the actual mental effort required was low and the measurable output minimal. Compared to sitting at a desk and focusing on a single task, it's far inferior for most people, who find that quite exhausting or demotivating.
About mental effort in meetings being lower than solving a technical issue, it is definitively true (most of the time), even though non-technical people cannot even grasp how much a difference there is.
In a previous software job, I was participating in a trade show. It was meeting after meeting, with both sales and technical aspects (I was paired with a sales guy). After several days like this, I remember vividly the sales guy saying how this trade show was good, but at the same time complaining how tired he was because all of these meetings. I kept it to myself, but for me, this was nearly like vacations compared to the day to day usual work
In a previous software job, I was participating in a trade show. It was meeting after meeting, with both sales and technical aspects (I was paired with a sales guy). After several days like this, I remember vividly the sales guy saying how this trade show was good, but at the same time complaining how tired he was because all of these meetings. I kept it to myself, but for me, this was nearly like vacations compared to the day to day usual work
I think that's a bit ungenerous to think that programmers are somehow different in this regard. Everyone hates attending boring meetings. And non-programmers also have heads down individual work they need to / would rather be doing.
However I agree that the extent of it is the key. I think most people actually hate running meetings (it's basically public speaking), but they hate writing documents even more. It's much easier to "voice over" something than to sit and write it out. It's also easier to enforce attendance than to police opening and actually reading documents. So meetings are the path of least resistance/effort.
However I agree that the extent of it is the key. I think most people actually hate running meetings (it's basically public speaking), but they hate writing documents even more. It's much easier to "voice over" something than to sit and write it out. It's also easier to enforce attendance than to police opening and actually reading documents. So meetings are the path of least resistance/effort.
Well people say they hate attending boring meetings, but when you observe what people do it's normally the coders who actively find ways to skip / who aren't setting up new meetings / are requesting fewer meetings. Other job roles, at least in my experience, tend to jump to a meeting as the first reaction. Developers will say: let's discuss it over email. Others say: let's hop on a call / grab a room. The number of meetings I've been in where there are multiple participants who don't have any obvious reason to be there, and who don't say anything throughout the entire meeting, is uncountable.
Now you're right it's obviously not that black and white, I'm generalizing. But I think devs often under-estimate how many people in a typical company perceive meeting other internal employees as amongst their primary outputs, as an end in and of itself, not just a means.
A good way to observe this in action is to try and enforce a rule that meetings must have pre-published agendas. Good luck with that! People will just work around it or write useless non-agendas because often a meeting is not to get something specific done, but is used more like a sort of coffee break to split up the day and give people something to look forward to between desk time.
Something else worth remarking on - a lot of people in sales or marketing roles never seem to use word processors. They communicate ideas by sending PowerPoint decks around, often with a density of words in the slides too high to actually project (only readable on hi-dpi screens). Where I last worked there were people whose working hours boiled down to meetings and PowerPoints. They could spend a whole week making a deck, which would only be seen by their colleagues in a meeting. I found it odd but maybe the slide templates help them structure their thoughts.
Now you're right it's obviously not that black and white, I'm generalizing. But I think devs often under-estimate how many people in a typical company perceive meeting other internal employees as amongst their primary outputs, as an end in and of itself, not just a means.
A good way to observe this in action is to try and enforce a rule that meetings must have pre-published agendas. Good luck with that! People will just work around it or write useless non-agendas because often a meeting is not to get something specific done, but is used more like a sort of coffee break to split up the day and give people something to look forward to between desk time.
Something else worth remarking on - a lot of people in sales or marketing roles never seem to use word processors. They communicate ideas by sending PowerPoint decks around, often with a density of words in the slides too high to actually project (only readable on hi-dpi screens). Where I last worked there were people whose working hours boiled down to meetings and PowerPoints. They could spend a whole week making a deck, which would only be seen by their colleagues in a meeting. I found it odd but maybe the slide templates help them structure their thoughts.
> you observe what people do it's normally the coders who actively find ways to skip / who aren't setting up new meetings / are requesting fewer meetings
Interesting - I actually chalk up that to two things: first, people in SWE roles having historically been given a tremendous amount of latitude for behavior that does not conform to "professional" norms. The freedom to dress however they want, work from home, and skip out on meetings they don't want to attend are all of a piece. And second, I think software engineering work is often (generalizing as well) less cross functional than other roles. Gathering requirements and understanding how it fits into a larger company plan is usually tasked out to PMs or tech leads, which is not something I've seen for Finance, HR, Legal, or other functional roles. So the need to schedule their own meetings is also lessened.
Interesting - I actually chalk up that to two things: first, people in SWE roles having historically been given a tremendous amount of latitude for behavior that does not conform to "professional" norms. The freedom to dress however they want, work from home, and skip out on meetings they don't want to attend are all of a piece. And second, I think software engineering work is often (generalizing as well) less cross functional than other roles. Gathering requirements and understanding how it fits into a larger company plan is usually tasked out to PMs or tech leads, which is not something I've seen for Finance, HR, Legal, or other functional roles. So the need to schedule their own meetings is also lessened.
I think the meetings people consider wasteful are not the ones with a lot of substantive content related to their work.
I was in yet another meeting the other day, and we had more "observers" than actual contributors / workers. Totally absurd. At the end of the meeting, some of the "observers" simply don't understand the meeting, and want a follow up meeting to discuss the meeting, so they discuss it in yet another meeting (presumably to appear intelligent so even more meetings can be scheduled.)
I've also noticed the PowerPoint issue: densely packed slides look ridiculous and don't project well. I think a lot of people wind up simply reading off the slides.
I've also noticed the PowerPoint issue: densely packed slides look ridiculous and don't project well. I think a lot of people wind up simply reading off the slides.
This is true. And the more meetings the better, because if a meeting starts to get serious, you can just drop for another meeting!
> Most people are a) bad at listening and b) hate meetings, but that doesn't stop them...
True, people are bad at both but I think many people view a 30 minute meeting where they can voice over an idea as a lower lift than sitting down and writing a well structured doc (see also: Loom). Plus, it's easier to enforce attendance than to enforce reading a document. So meetings are the path of least resistance.
True, people are bad at both but I think many people view a 30 minute meeting where they can voice over an idea as a lower lift than sitting down and writing a well structured doc (see also: Loom). Plus, it's easier to enforce attendance than to enforce reading a document. So meetings are the path of least resistance.
Which is unacceptable for an engineer who must participate in architecture meetings.
does anyone do that anymore?
for me this is the real failure and design documentation being shitty is just a symptom
group design is a really important skill, and people don't even recognize that its a thing
for me this is the real failure and design documentation being shitty is just a symptom
group design is a really important skill, and people don't even recognize that its a thing
Does anyone do what? Fail to pay attention/retain architecture via meeting? Because yeah engineers definitely tend keep working/browse Reddit during meetings because they feel they have better stuff to do.
[deleted]
doesn't Amazon have a similar structure, tho? i don't know what it's actually like to work there (anyone who does feel free to chime in) but i've interviewed and from what I can tell they put a heavy emphasis on documentation. it's tough to find a bigger and more siloed company than Amazon, and it seems to work for them.
Amazon is high documentation, high meetings culture. The documentation is reviewed by peers, bar raisers, and leaders in a process called document read before being official.
Edit: Someone asked for more detail on high meeting culture. There are constant meetings between cross-functional teams, various leadership stakeholders, and ongoing operational planning. That is not including your day to day meetings within your sub team or the follow up meetings from doc reads or the new team launch meetings, etc. Amazon tech is a high meeting culture.
Edit: Someone asked for more detail on high meeting culture. There are constant meetings between cross-functional teams, various leadership stakeholders, and ongoing operational planning. That is not including your day to day meetings within your sub team or the follow up meetings from doc reads or the new team launch meetings, etc. Amazon tech is a high meeting culture.
Sure, but oftentimes technical documentation is severely lacking. PRFAQs, initial design docs, etc. are thoughtfully created and thoroughly reviewed, but the actual implementation lacks the documentation required to make onboarding (be it new team members or new dependent teams) as smooth as it could be. My favorite is finding an out of date Wiki page from 6 years ago that contains a partial list of API method names, descriptions if you're lucky, and then nothing else, not even a link to the service's AAA page/etc. or a high-level summary of what the service _does_ or _why_. With how many moving parts there are and how inaccessible non-platform-level documentation is, the new hire experience at Amazon can be rather daunting. Even SDE1/2s that are a year in often have a very incomplete picture of what's going on in their own domain space. Too much tribal knowledge.
[deleted]
so the worst of both worlds
Why? I think this sounds great.
Read an amazon 6 pager... then try to write one, about anything. and then invite all of your co-workers to pick apart every single line of your document.
Correct. Be careful about sharing a document in progress, notes, or just simple thoughts in text. People will pick it apart word by word. Why? It is the culture Amazon created. Sometimes it helps. Sometimes it's a waste of everyone's time.
If you are writing for reviews, you are not writing for your peers. The question is: who will be using the documents?
this statement needs some detail, "high meetings" is obscuring that meetings use the docs (not meetings with no agenda or lots of presentations). meeying use docs as the primary driver, be that a narrative or analysis of a dataset
As someone who has to use Amazon's external documentation: it's absolutely terrible. Worst docs of any company we have to interact with at the API level.
They need high documentation to support their employee churn.
> feel free to chime in
Pun intended?
Pun intended?
[deleted]
Also the problem of incentives. I can write well. Why should I bother to do so when I am not rewarded for that?
So I just write crap as well.
So I just write crap as well.
> a) bad at writing and b) hate reading
Why does everyone else has to pay the insane price for that?
Why does everyone else has to pay the insane price for that?
High-Documentation is so out of fashion, for all the wrong reasons. If you are designing anything that is intended to last longer than 6 months, documentation is a critical part of the system.
Meetings are great for communicating with people here and now, but only writing can communicate with people from the future. When you meet with your current colleagues, spare a thought for your future colleagues who haven’t yet joined, and do them a favor by writing things down.
Ability to use written communication is a major differentiator between junior and senior engineer.
Meetings are great for communicating with people here and now, but only writing can communicate with people from the future. When you meet with your current colleagues, spare a thought for your future colleagues who haven’t yet joined, and do them a favor by writing things down.
Ability to use written communication is a major differentiator between junior and senior engineer.
This reminds me of when leadership announces a policy over email. Sure, all the people who got the email can follow it, but what about people who join the team in the future? Either they find out about the policy when they violate it and get reprimanded, or they hear about it via word of mouth.
I've seen it a number of times in my career.
I've seen it a number of times in my career.
For sure! Why can't it be "we have updated/created X policy, please find it here: <link to document in policy repository>" ? Is that so much harder?
Most document management systems have a notification system built-in so that you can automatically email your all-staff mailing list when there is an update. It's very much a solved problem.
Most document management systems have a notification system built-in so that you can automatically email your all-staff mailing list when there is an update. It's very much a solved problem.
Writing is definitely a critical skill for software development. At my last "staff+" job, I spent most of the time writing documents that seemingly nobody ever actually read. I also reviewed a bunch of them.
Hard agree.
My current workplace culture (at least in the HW dept) is much more towards zero-documentation than anything I have experienced before and it has been a nightmare as a relatively new employee.
I waste so much time in reviews because I have done something non-standard despite having checked the standards docs but it turns out the standards have changed and no one bothered to update the docs. We don't even write specifications for products before we start work on them; if I make some architectural changes during the design, there is nowhere to record it. Drives me insane.
IMO there are two things that should be documented about any project: 1. The product itself: at least its interfaces, features and general architecture 2. The process of design: what changes were made vs the original spec, why, and when
If you want to know anything contained in that set of information here, you have to know who worked on the project so you can ask them about it, and then they have to be able to remember. It's not uncommon that changes are suggested and discussed multiple times within a project, or that changes are made but the reasons why are forgotten before the project is even complete.
I often joke that projects here are more "observed" than managed.
Exactly as you say - emails/meetings are ideal tools for discussion and decision making but for lasting records, you need documentation.
My current workplace culture (at least in the HW dept) is much more towards zero-documentation than anything I have experienced before and it has been a nightmare as a relatively new employee.
I waste so much time in reviews because I have done something non-standard despite having checked the standards docs but it turns out the standards have changed and no one bothered to update the docs. We don't even write specifications for products before we start work on them; if I make some architectural changes during the design, there is nowhere to record it. Drives me insane.
IMO there are two things that should be documented about any project: 1. The product itself: at least its interfaces, features and general architecture 2. The process of design: what changes were made vs the original spec, why, and when
If you want to know anything contained in that set of information here, you have to know who worked on the project so you can ask them about it, and then they have to be able to remember. It's not uncommon that changes are suggested and discussed multiple times within a project, or that changes are made but the reasons why are forgotten before the project is even complete.
I often joke that projects here are more "observed" than managed.
Exactly as you say - emails/meetings are ideal tools for discussion and decision making but for lasting records, you need documentation.
Yes!!
Agile taught us working software over comprehensive documentation, but it also made huge generation of people thinking that all documentation was bad, and not just "comprehensive" (or "overblown").
Documentation (words) is how many complex concepts are communicated.
I've built a requirements management system to handle this (https://userdoc.fyi), and it's made many projects I've worked on 200% easier for developers, project managers, and all stockholders.
I think high-Documentation is out of fashion as a reaction to agile, but things are swinging back the other way.
Agile taught us working software over comprehensive documentation, but it also made huge generation of people thinking that all documentation was bad, and not just "comprehensive" (or "overblown").
Documentation (words) is how many complex concepts are communicated.
I've built a requirements management system to handle this (https://userdoc.fyi), and it's made many projects I've worked on 200% easier for developers, project managers, and all stockholders.
I think high-Documentation is out of fashion as a reaction to agile, but things are swinging back the other way.
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 some very specific personality types.
[1] https://blog.alan.com/bien-etre-au-travail/who-we-are-and-ho...
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 some very specific personality types.
[1] https://blog.alan.com/bien-etre-au-travail/who-we-are-and-ho...
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.
There's nothing on that page that mentions "no managers"
From the outside, Gitlab seems to have solved this with a medium-sized org with all remote, and it sounds like a dream remote workplace.
Async communication, full transparency, 90-day retention in slack which forces decisions into documentation if it's important, issues/threads for discussions, and handbook for SOPs [1]
Anyone have experience with this directly that can speak to if this works in practice?
Or is Gitlab just really good at marketing their methodology as a tool to sell more subscriptions?
1 - https://about.gitlab.com/company/culture/all-remote/handbook...
Async communication, full transparency, 90-day retention in slack which forces decisions into documentation if it's important, issues/threads for discussions, and handbook for SOPs [1]
Anyone have experience with this directly that can speak to if this works in practice?
Or is Gitlab just really good at marketing their methodology as a tool to sell more subscriptions?
1 - https://about.gitlab.com/company/culture/all-remote/handbook...
GitLab employee here. Can confirm, it works exactly as advertised to the outside world.
GitLab team member here for over 3 years. Can confirm, it works exactly as advertised. The detailed description above is totally in line with my experience.
The two essential elements of why this works.
1. Communication (both formal — work related — and informal) is explicitly defined. https://about.gitlab.com/handbook/communication/
2. There's absolute executive sponsorship to work "handbook-first." If it's not in the handbook, it's as if it doesn't exist. The top-down belief in the system enables it to function. https://about.gitlab.com/company/culture/all-remote/handbook...
We recently codified the operating model in a course we're calling TeamOps. It's a first iteration, but anyone is welcome to take the course and provide feedback. https://about.gitlab.com/teamops/
The two essential elements of why this works.
1. Communication (both formal — work related — and informal) is explicitly defined. https://about.gitlab.com/handbook/communication/
2. There's absolute executive sponsorship to work "handbook-first." If it's not in the handbook, it's as if it doesn't exist. The top-down belief in the system enables it to function. https://about.gitlab.com/company/culture/all-remote/handbook...
We recently codified the operating model in a course we're calling TeamOps. It's a first iteration, but anyone is welcome to take the course and provide feedback. https://about.gitlab.com/teamops/
GitLab team member here.
Sharing a personal insight - I'm currently moving flats in the Nuremberg area in Germany which is a little hectic because forced out by the new house flat owner. Async work enables me to take calls and go shopping to organize the move, whilst shifting work hours into the evening or early morning. I am also able to take paid time off (PTO) when needed to prepare the move early December. In my previous office job, I would have needed to reserve a lot of vacation days for this, and ask for permission to start later than 10am, or leave earlier than 4pm. Here at GitLab, I am my own manager [0] and take care about my working hours - it is a personal freedom, and I appreciate these less stressful times a lot. In return, I can take time to focus on private life, and come back refreshed to produce great results (blog posts, talks, helpful replies here and other community channels, etc.).
What I learned in the past 2 years and 9 months at GitLab, is to provide as much context as needed so that someone else in a different timezone can continue async, and is not blocked by anything (low context communication [1]). Also, short toes [2] enable everyone to add their thoughts and opinions, and work with the directly individual responsible (DRI) for the best outcome.
The Slack retention period of 90 days is a great reminder (and also enforcement) to document everything in the handbook. Example from today: I learned that Google docs supports the colon for emoji live-search. Thought of sharing in Slack, but then went with editing the handbook and sending a MR [3] to help everyone find this little efficiency tip in the future - that said, Slack is not a knowledge base. The GitLab handbook is.
Thinking about the past year with a public discussion about speaker diversity at events, I admire our teams to take action to ensure events align with our diversity, inclusion and belonging values. We have updated our event requirements for speakers (MR [4], handbook page [5]), and are working with event organizers and the wider community to help with mentoring and coaching to inspire future speakers.
Last but not least, transparency [6]. Internal and external, I can read and learn async at my own pace. Most of my meetings are optional, and the meeting notes/recording are detailed, with follow-up actions. You'll never recap old meeting notes the next time but reference actioned issues and merge requests. Many issues/epics are public - if you'd like to learn more about my thought leadership strategy for Observability, and all content created and planned, you can follow this epic [7] or my profile activity [8] for example.
I haven't met everyone in-person yet, because of the pandemic, and travel only for some events (KubeCon EU/NA, PromCon EU [9] [10]), but I am looking forward to meet and value these moments. Hard to describe, I feel incredibly connected to my teams albeit living far far away. :-)
Happy to share more thoughts and insights - my role is on the community relations/developer evangelism team, I'm the stable counterpart for the product teams, and collaborate in cross-functional initiatives often. [11] My first [12] and second [13] year blog posts share more experiences too :-)
[0] https://about.gitlab.com/handbook/leadership/#managers-of-on...
[1] https://about.gitlab.com/handbook/communication/#effective-c...
[2] https://about.gitlab.com/handbook/values/#short-toes
[3] https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_request...
[4] https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_request...
[5] https://about.gitlab.com/handbook/marketing/corporate-market...
[6] https://about.gitlab.com/handbook/values/#transparency
[7] https://gitlab.com/groups/gitlab-com/marketing/-/epics/2593
[8] https://gitlab.com/dnsmichi
[9] https://dnsmichi.at/2022/06/13/my-kubecon-eu-experience-firs...
[10] https://opsindev.news/archive/2022-11-23/#promcon-eu
[11] https://about.gitlab.com/handbook/marketing/community-relati...
[12] https://dnsmichi.at/2021/03/02/my-1st-year-all-remote-at-git...
[13] https://dnsmichi.at/2022/03/02/2-years-all-remote-and-2022-v...
Sharing a personal insight - I'm currently moving flats in the Nuremberg area in Germany which is a little hectic because forced out by the new house flat owner. Async work enables me to take calls and go shopping to organize the move, whilst shifting work hours into the evening or early morning. I am also able to take paid time off (PTO) when needed to prepare the move early December. In my previous office job, I would have needed to reserve a lot of vacation days for this, and ask for permission to start later than 10am, or leave earlier than 4pm. Here at GitLab, I am my own manager [0] and take care about my working hours - it is a personal freedom, and I appreciate these less stressful times a lot. In return, I can take time to focus on private life, and come back refreshed to produce great results (blog posts, talks, helpful replies here and other community channels, etc.).
What I learned in the past 2 years and 9 months at GitLab, is to provide as much context as needed so that someone else in a different timezone can continue async, and is not blocked by anything (low context communication [1]). Also, short toes [2] enable everyone to add their thoughts and opinions, and work with the directly individual responsible (DRI) for the best outcome.
The Slack retention period of 90 days is a great reminder (and also enforcement) to document everything in the handbook. Example from today: I learned that Google docs supports the colon for emoji live-search. Thought of sharing in Slack, but then went with editing the handbook and sending a MR [3] to help everyone find this little efficiency tip in the future - that said, Slack is not a knowledge base. The GitLab handbook is.
Thinking about the past year with a public discussion about speaker diversity at events, I admire our teams to take action to ensure events align with our diversity, inclusion and belonging values. We have updated our event requirements for speakers (MR [4], handbook page [5]), and are working with event organizers and the wider community to help with mentoring and coaching to inspire future speakers.
Last but not least, transparency [6]. Internal and external, I can read and learn async at my own pace. Most of my meetings are optional, and the meeting notes/recording are detailed, with follow-up actions. You'll never recap old meeting notes the next time but reference actioned issues and merge requests. Many issues/epics are public - if you'd like to learn more about my thought leadership strategy for Observability, and all content created and planned, you can follow this epic [7] or my profile activity [8] for example.
I haven't met everyone in-person yet, because of the pandemic, and travel only for some events (KubeCon EU/NA, PromCon EU [9] [10]), but I am looking forward to meet and value these moments. Hard to describe, I feel incredibly connected to my teams albeit living far far away. :-)
Happy to share more thoughts and insights - my role is on the community relations/developer evangelism team, I'm the stable counterpart for the product teams, and collaborate in cross-functional initiatives often. [11] My first [12] and second [13] year blog posts share more experiences too :-)
[0] https://about.gitlab.com/handbook/leadership/#managers-of-on...
[1] https://about.gitlab.com/handbook/communication/#effective-c...
[2] https://about.gitlab.com/handbook/values/#short-toes
[3] https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_request...
[4] https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_request...
[5] https://about.gitlab.com/handbook/marketing/corporate-market...
[6] https://about.gitlab.com/handbook/values/#transparency
[7] https://gitlab.com/groups/gitlab-com/marketing/-/epics/2593
[8] https://gitlab.com/dnsmichi
[9] https://dnsmichi.at/2022/06/13/my-kubecon-eu-experience-firs...
[10] https://opsindev.news/archive/2022-11-23/#promcon-eu
[11] https://about.gitlab.com/handbook/marketing/community-relati...
[12] https://dnsmichi.at/2021/03/02/my-1st-year-all-remote-at-git...
[13] https://dnsmichi.at/2022/03/02/2-years-all-remote-and-2022-v...
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 service, and other backgrounds who can spot trash (in their area of expertise) when they see 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 service, and other backgrounds who can spot trash (in their area of expertise) when they see it.
Yeah, having worked at a company who had to publish documentation, the technical writer was definitely an essential role. The engineer can write up the documentation, but you need someone external who can review, and interrogate what is written before it goes out. People are very poor at knowing what they need to communicate.
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.
The same is true for testing though. Lots of shops write as few tests as possible, if any, because the devs don’t have to so they think their way is just fine.
I went from working as the annoying guy asking for tests and docs to the manager and we saw a huge improvement in performance, feature release and a reduction in bugs hitting prod. I can attest their way does not work just fine.
I went from working as the annoying guy asking for tests and docs to the manager and we saw a huge improvement in performance, feature release and a reduction in bugs hitting prod. I can attest their way does not work just fine.
Designers to design, draughtspeople to draught, archivists to archive.
Engineering entails a lot of secretarial work that has been "streamlined" by expecting engineers to do it themselves rather than employing professional secretaries to do so. The end result is that it is often left un-done.
The "enforcers" you talk about are basically secretaries, no? Trained individuals with enough understanding of the work at hand to record and file it in a context-aware manner.
Reminds me of the "surgical team" model from The Mythical Man Month [1] wherein there is a suite of people provided to every engineer to minimise their work outside of design and implementation. (At least that's how I remember it, it's a few years since I read it)
[1]: https://en.wikipedia.org/wiki/The_Mythical_Man-Month
Engineering entails a lot of secretarial work that has been "streamlined" by expecting engineers to do it themselves rather than employing professional secretaries to do so. The end result is that it is often left un-done.
The "enforcers" you talk about are basically secretaries, no? Trained individuals with enough understanding of the work at hand to record and file it in a context-aware manner.
Reminds me of the "surgical team" model from The Mythical Man Month [1] wherein there is a suite of people provided to every engineer to minimise their work outside of design and implementation. (At least that's how I remember it, it's a few years since I read it)
[1]: https://en.wikipedia.org/wiki/The_Mythical_Man-Month
I really think this is true, and we usually rely on tech leaders or PMs to do this job, but in reality maybe we should consider having people who are responsible for this full time (or at least part time).
I think having advocates or evangelists within the company is important also, people who can interject "good answer, I think it would be valuable to copy this in a document for the next time someone asks"
I think having advocates or evangelists within the company is important also, people who can interject "good answer, I think it would be valuable to copy this in a document for the next time someone asks"
In order for this to work, you also need a high-reading work culture, which is distinct from a high-writing (documentation) work culture.
As the only person on my team who routinely documents my work (or at least who does so in a place visible to others), I definitely agree. I get very tired of people asking me things about my work where the reply is "it's in the docs, please check here: <link>." Makes me feel like a directory.
as someone who often would like to read documentation but have to end up asking the owner where it is like you describe
My problem is that there are too many pages that may or may not be relevant/and/or up-to-date, I want to know if there is a better way? I can't just read every document the company has on the topic in vain hopes for the answer. For example, I recently started working on my company's mobile app - noone has looked at it in a few months so its an ideal candidate for this kind of knowledge.
Despite that, I didn't go to confluence, because 99% of the stuff on there is half-finished drafts, and stuff aimed at our b2b customers, so I don't hold much hope in finding a solution to something which in principle ought to be very simple, like setting up my dev environment. In this case, the original project lead is no longer with the company, I had to ask a couple people who worked with it in the past, and it turns out they no longer knew how, and the documentation which had been written both didn't include it (it was customer-facing) and was also so out-of-date as to be irrelevant. I have no doubt that whatever developer made the app stopped writing documentation because they felt nobody would read it if they did! it's a self-reinforcing cycle.
I guess the only answer, as some others have mentioned, is a predictable organization system for the documentation, which crucially is actually taught to newcomers.
My problem is that there are too many pages that may or may not be relevant/and/or up-to-date, I want to know if there is a better way? I can't just read every document the company has on the topic in vain hopes for the answer. For example, I recently started working on my company's mobile app - noone has looked at it in a few months so its an ideal candidate for this kind of knowledge.
Despite that, I didn't go to confluence, because 99% of the stuff on there is half-finished drafts, and stuff aimed at our b2b customers, so I don't hold much hope in finding a solution to something which in principle ought to be very simple, like setting up my dev environment. In this case, the original project lead is no longer with the company, I had to ask a couple people who worked with it in the past, and it turns out they no longer knew how, and the documentation which had been written both didn't include it (it was customer-facing) and was also so out-of-date as to be irrelevant. I have no doubt that whatever developer made the app stopped writing documentation because they felt nobody would read it if they did! it's a self-reinforcing cycle.
I guess the only answer, as some others have mentioned, is a predictable organization system for the documentation, which crucially is actually taught to newcomers.
> I can't just read every document the company has on the topic in vain hopes for the answer.
If your documentation doesn't have a search feature, that's the first thing you need to fix.
If you're just bad at searching, well that's a very valuable and learnable skill.
> like setting up my dev environment
> the documentation which had been written both didn't include it (it was customer-facing
The user docs and the dev docs should be different corpses, searchable separately. What you describe sounds very disorganized.
If your documentation doesn't have a search feature, that's the first thing you need to fix.
If you're just bad at searching, well that's a very valuable and learnable skill.
> like setting up my dev environment
> the documentation which had been written both didn't include it (it was customer-facing
The user docs and the dev docs should be different corpses, searchable separately. What you describe sounds very disorganized.
There are two sides to the coin with not being able to find things - sometimes it is, as you say, because you are bad at searching for things, but sometimes things haven't been made in an easily searchable way. To name just three:
- sections with ambiguous names;
- multiple sections with the same name; or
- information is split across separate sections/pages.
Worst case is that there is detailed documentation but it's all in the comments of twenty different Jira tickets.
I do agree that user docs and dev docs should be separated though, as should specifications and development logs.
Worst case is that there is detailed documentation but it's all in the comments of twenty different Jira tickets.
I do agree that user docs and dev docs should be separated though, as should specifications and development logs.
> I guess the only answer, as some others have mentioned, is a predictable organization system for the documentation, which crucially is actually taught to newcomers.
Precisely - just as you'd on-board new hires with information about codes of practise for development (code styles, nuances of internal git practice, etc.) you ought to at least have a "Contribution Guidelines" or similar doc that sets out how to structure and record information in the docs.
Precisely - just as you'd on-board new hires with information about codes of practise for development (code styles, nuances of internal git practice, etc.) you ought to at least have a "Contribution Guidelines" or similar doc that sets out how to structure and record information in the docs.
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.
Our work culture's obsession with meetings, which is dwindling, it seems, is due in large part to our desire to perform as part of 'productivity theater.' this has mostly been driven up by wfh. but it's interesting to me that so many people focus on performativity vs. output
I think about this a lot. "Managers" are under pressure to make sure their teams are meeting goals/deadlines/whatever, so they are anxious, so they make efforts to observe and oversee "performance". Seeing people in meetings and diligently "working" makes them feel better about their teams' performance. But what really matters is outcome...which is very difficult to measure for a lot of software teams, and even harder for individuals. The irony is that the efforts to measure/ensure performance, in many cases, actually impede material progress towards the desired outcomes.
On the other hand, thirty minutes a week seems like a small overhead to pay if you’re concerned a team might otherwise lose focus & direction entirely. Not, to be clear, that they are lazy, but instead that they could be diligently working… on the wrong thing.
I can understand it both ways.
I can understand it both ways.
It's certainly a spectrum. 1<>1s and vision alignment meetings are super important. Standups too, if that's your thing (I like them, but they must be run well). A lot of other stuff can start to get noisy in my opinion.
Is it dwindling? I think the number of hours of meetings I attended approximately quadrupled due to WFH. Limited conference rooms making > 1 hr meetings impossible was wonderful.
Or are you saying it was dwindling, but it surged up due to wfh? Then I guess I agree, though I’m not sure if it’s due to productivity theater, or physical constraints being removed
Or are you saying it was dwindling, but it surged up due to wfh? Then I guess I agree, though I’m not sure if it’s due to productivity theater, or physical constraints being removed
I was watching a DistroTube video where he was ranking multiple windows managers, and he explicitly refused to give i3wm points for having great documentation because "it's the bare minimum". Except all the other ones had crap documentation.
One can only dream everything had documentation as great as i3wm's as a bare minimum.
One can only dream everything had documentation as great as i3wm's as a bare minimum.
All developers should spend time working in support. That time will make them appreciate the incredible power and utility that documentation provides to everyone...including your future self.
I find it to be really interesting for the first day or two...then I realize that our customers are often really terrible people using our product for really bad reasons and it undermines my whole faith in the project
Yeah, that's the downside to learning about end-users.
But it's better to know than to be ignorant, usually.
But it's better to know than to be ignorant, usually.
At my company we make all meetings optional, this really helps create the right incentives both for hosts and attendees. As a result we have very few meetings, but the ones we have work well. https://www.synura.com/handbook/general/meetings/#all-non-11...
>>> It’s not just about the meeting, which is itself a thirty to sixty-minute intrusion on someone’s day. It’s about the time wasted anticipating a meeting, where people feel they don’t have the time to plunge into an important project.
Oh god yes! This - a thousand times this !!
Oh god yes! This - a thousand times this !!
I've also seen a lot of benefit of grouping recurring meetings all in the same time slot daily. I.e. all team rituals from 10-11 am daily.
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 <whatever>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.
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.
With uBlock
*SmoothScroll*$scriptadblock all the scripts =/
I think this approach has many benefits. The main problem with most collaborations in which documents are used to replace conversation is that without a disciplined framework for structuring documents it's very easy to get lost in them.
-documents go out of date, people are usually up to the minute
-documents don't allow you to ask questions people do
-documents never forget, people do (not forgetting seems like a good thing but try working through a 5-10 year old team wiki or OneNote and you'll see why it can be good)
-documents go out of date, people are usually up to the minute
-documents don't allow you to ask questions people do
-documents never forget, people do (not forgetting seems like a good thing but try working through a 5-10 year old team wiki or OneNote and you'll see why it can be good)
Is there any way to achieve this within Microsoft's suite?
Sadly we adopted Microsoft O365, SharePoint, Teams. How can you organize the org effectively is beyond me, how does MS do it? Are they actually using their own tools they sell others?
In our org, some departments/teams/sites have just a SP, Others have a teamspace with separate SP/document store.
Worse, any meaningful file structure/hierarchy you come up with gets sabotaged when new channels are created as they automatically introduce new folders. You cannot bind a teams channel to a separate folder in a SharePoint. Also, We have private project teams springing up and large fragmentation of information. If you do not know that a certain project space was set up you cannot find or join it.
Going with a "single Teamspace" for the whole org doesn't work either without being able to have nested channels/groups. The org is too large and complex.
I'd love to have a gitlab style handbook to be used in our org to organize knowledge and information, but I do not know if and how it could be set up technically.
Sadly we adopted Microsoft O365, SharePoint, Teams. How can you organize the org effectively is beyond me, how does MS do it? Are they actually using their own tools they sell others?
In our org, some departments/teams/sites have just a SP, Others have a teamspace with separate SP/document store.
Worse, any meaningful file structure/hierarchy you come up with gets sabotaged when new channels are created as they automatically introduce new folders. You cannot bind a teams channel to a separate folder in a SharePoint. Also, We have private project teams springing up and large fragmentation of information. If you do not know that a certain project space was set up you cannot find or join it.
Going with a "single Teamspace" for the whole org doesn't work either without being able to have nested channels/groups. The org is too large and complex.
I'd love to have a gitlab style handbook to be used in our org to organize knowledge and information, but I do not know if and how it could be set up technically.
Ex-Microsoft, current GitLab employee here. The way you describe using Microsoft's tools in your company is pretty much how things worked at Microsoft while I was there 3 years ago.
If you'd like to build a handbook similar to GitLab's, this page of our handbook can be a great starting point: https://about.gitlab.com/company/culture/all-remote/handbook...
> The way you describe using Microsoft's tools in your company is pretty much how things worked at Microsoft
That is mind boggling. How on earth can MS have an efficient knowledge management with this setup?
How frustrating was it too use for you?
The most sensible way forward seems to me would be just set up a single company SharePoint with a doc store with a predefined data layout. No associated team space around that. Move communication 100% to slack. Link / pin the relevant SP folders to the slack channels.
Just for the dev team this would work as we never moved chat from slack to teams. But we need to
1. interact with the less technical parts of our org (product management, quality & regulatory, BI, V&V, Legal etc)
2. Interact with colleagues from other subsidiaries.
They all use teams, so conversations & especially meetings will happen on teams, people will still store docs and notes there just out of convenience or lazyness.
I do not know how to solve that conundrum.
That is mind boggling. How on earth can MS have an efficient knowledge management with this setup?
How frustrating was it too use for you?
The most sensible way forward seems to me would be just set up a single company SharePoint with a doc store with a predefined data layout. No associated team space around that. Move communication 100% to slack. Link / pin the relevant SP folders to the slack channels.
Just for the dev team this would work as we never moved chat from slack to teams. But we need to
1. interact with the less technical parts of our org (product management, quality & regulatory, BI, V&V, Legal etc)
2. Interact with colleagues from other subsidiaries.
They all use teams, so conversations & especially meetings will happen on teams, people will still store docs and notes there just out of convenience or lazyness.
I do not know how to solve that conundrum.
We use a shared OneNote, team of 20-50
Easy to use, desktop app, search, and crucially highlights new changes and additions so you can see something is updated
Easy to use, desktop app, search, and crucially highlights new changes and additions so you can see something is updated
"High-documentation" isn't the cure, either. Just write quality software with well-defined interfaces, minimal dependencies and smooth building processes. I want to be able to build the thing without frustration, to start playing with it in order to learn its internals and debug it. Only then can I be comfortable enough to start implementing features and changes.
It's devastating to learn after more than 20 years in the industry that the secret is "Just write quality software with well-defined interfaces, minimal dependencies and smooth building processes". If I and my colleagues had known only sooner about this straightforward and actionable advice...
That’s how I often use documentation - start documenting something, then ask myself “should the code be fixed to avoid the need to document this part? Yes, yes it should”.
A long provisioning instruction became much shorter as a result of automating it by reducing the need to document.
A long provisioning instruction became much shorter as a result of automating it by reducing the need to document.
> We deliberately encourage people to create documents rather than build slide decks. Slide decks can mask poorly-written content with decorative font, sleek formatting, and compelling images.
>In a document, the content is all you have. It forces people to focus on communicating their ideas as clearly as possible.
>In a document, the content is all you have. It forces people to focus on communicating their ideas as clearly as possible.
Documentation is worse than code. It's often outdated, difficult to understand and full of useless information. In every company I have been people hate to read docs and nobody wants to maintain them.
I am not sure what a good alternative might be.
That's a culture problem. It boils down to documentation being a second-class citizen which is not included in the "definition of done".
It just needs to be better than meetings to be well, better than meetings. Nothing is worse than meetings.
My personal policy was "No regularly-scheduled meetings" (which included things like daily standups).
But I worked for a Japanese corporation, so we had regularly-scheduled meetings. I was able to reduce them, though.
But I worked for a Japanese corporation, so we had regularly-scheduled meetings. I was able to reduce them, though.
I love companies that can actually thrive with this way of working but it only works at a certain size. This only works in a senior heavy, relatively flat engineering org. Once process ramps up due to new compliance demands or HR wants more of a mixed skill level in engineering, rapid fire product delivery and async culture dies out. I think this could be sustained in a software company in the right context, but orgs eyeing unicorn valuations or headline exits only leverage this way of working until they need to recalibrate.
[deleted]
I thought this was a well written article and I loved the graphics (especially the one about 30 minute meetings actually taking 68 minutes). However, it's worth noting that this company is fairly small (48 members according to their About page) and that the group has been together for quite some time.
I'm not sure how well this would scale past the Dunbar number, or for organizations growing rapidly.
Either way, I'm glad they published this.
I'm not sure how well this would scale past the Dunbar number, or for organizations growing rapidly.
Either way, I'm glad they published this.
I wish more people adopted Andy Grove's thoughts on meetings.
https://jondouglas.dev/lets-not-meet/
This company seems to "get it" though. We ought to protect our attention more often.
I'd take documentation over no documentation any day. Even if it's 4 years old and was last updated by a person who left for a competitor.
https://jondouglas.dev/lets-not-meet/
This company seems to "get it" though. We ought to protect our attention more often.
I'd take documentation over no documentation any day. Even if it's 4 years old and was last updated by a person who left for a competitor.
I read through your link and it rang hollow to me. Care to share your insight?
My blog is the insight. The book I recommend may give more context as to why it is important.
The problem with attempting a high-documentation culture is that it's very difficult to have a closed feedback loop. I see this all the time. Someone writes up "Here's what tool X does, and here's how to use it", and it never works. There's always some environment variable you forgot to set, or some local file, or some path that's literally /home/$USER/... in the code, or even worse "Here's the built binary, which isn't the same as the binary that gets built from source". How do you fix this? As part of your documentation process you get someone else to actually read and reproduce and review the document. And that person needs to be at arms distance to avoid shared knowledge being elided. To enforce this you also probably need it to gate atleast reasonably large PRs. You need ways to ensure the documentation doesn't go out of date. What am I saying? This only works in a process heavy environment. Which goes directly against what the author of this article says - which is a red flag. What can easily be the case here is you have 50 engineers all building new stuff, all writing reams of documentation which probably isn't at all useful, but because no one ever reads any of it, you never pay the cost...
Then you hire someone and for the first 6 months their life is hell until they clock on to what everyone else is doing and just ignore whatever everyone else is working on and plough their own furrow. Sure, we've now got 17 different poorly documented logging libraries (because no one wanted to invest in adopting anyone elses), but every individual developer is writing plenty of documentation! Oh and god forbid you disturb the author with questions outside of the 1 very short window for meetings in 1 specific time zone. Their careers page says "Join teammates from Hawaii to Brazil to Germany". Their meeting time is 6-9pm in Germany every day and 7am to 10am Hawaii time.
Then you hire someone and for the first 6 months their life is hell until they clock on to what everyone else is doing and just ignore whatever everyone else is working on and plough their own furrow. Sure, we've now got 17 different poorly documented logging libraries (because no one wanted to invest in adopting anyone elses), but every individual developer is writing plenty of documentation! Oh and god forbid you disturb the author with questions outside of the 1 very short window for meetings in 1 specific time zone. Their careers page says "Join teammates from Hawaii to Brazil to Germany". Their meeting time is 6-9pm in Germany every day and 7am to 10am Hawaii time.
I've worked at high-documentation companies and low-documentation companies.
Documentation is hard to create and hard to maintain. It is essentially a simulation of an underlying reality, and that underlying reality *always* changes faster than the documentation can. So the documentation ends up being spotty, except for the parts that you find a way to automate. It's hard to automate all documentation, since so much knowledge is trapped in the analog world, and in peoples' minds.
Companies like storytell.ai are trying to solve the problem of creating documentation and written artifacts automatically out of Zoom recordings, etc. Others, like WeRice, are trying to create it out of videos of maintenance work done on equipment in the wild. I respect both efforts a lot. It's a hard problem to tackle.
* https://www.storytell.ai/
* https://we-rice.com/
Documentation is hard to create and hard to maintain. It is essentially a simulation of an underlying reality, and that underlying reality *always* changes faster than the documentation can. So the documentation ends up being spotty, except for the parts that you find a way to automate. It's hard to automate all documentation, since so much knowledge is trapped in the analog world, and in peoples' minds.
Companies like storytell.ai are trying to solve the problem of creating documentation and written artifacts automatically out of Zoom recordings, etc. Others, like WeRice, are trying to create it out of videos of maintenance work done on equipment in the wild. I respect both efforts a lot. It's a hard problem to tackle.
* https://www.storytell.ai/
* https://we-rice.com/
This can be improved with two sets of links for each doc. A set of manually added links to previous related material, with optional note. New links can be added by anyone.
And a set of automatically generated reverse links, to documents that referenced the one being viewed.
Both kinds of links help create continuity and context.
And a set of automatically generated reverse links, to documents that referenced the one being viewed.
Both kinds of links help create continuity and context.
Again, that a lot of extra work, and the automatic reverse links are v tooling dependent. You don't get them with Confluence or gDocs, fwiw.
Nor do these suggestions solve the problem of doc creation.
What many people ignore in these discussions is the real tradeoff between "time spent in meetings with people who can answer questions" vs "time spent by non-professional writers trying to be clear for strangers".
Nor do these suggestions solve the problem of doc creation.
What many people ignore in these discussions is the real tradeoff between "time spent in meetings with people who can answer questions" vs "time spent by non-professional writers trying to be clear for strangers".
> It is essentially a simulation of an underlying reality, and that underlying reality always changes faster than the documentation can.
That probably depends on how you prioritize it. You can dictate that the docs (and the tests) be written before features are added.
That probably depends on how you prioritize it. You can dictate that the docs (and the tests) be written before features are added.
Personally I feel documentation wont be such hard thing to do if ppl are not very particular about formatting and making it look good.
The real problem is the document quality. Most of time reading a low-quality document will waste plenty of time while talking or meeting is more efficient than reading a misleading document. The other problem is that is hard to keep the document ‘fresh’, and this will lead you in the wrong direction which is wasting time.
I've been working with Tremendous and have become a believer in high-documentation, low-meeting work culture. Employees are happier, more productive and have more head space to develop creative contributions.
I like this a lot in principle but would add two notes about doing this in practice:
1. Promote self-documentation as much as possible—e.g. meeting notes typed straight into Google Doc, discussions typed straight into Slack, issues typed straight into GitHub, comments typed straight into code—so you’re documenting as you go in a way that’s automatically archived and searchable for future reference. There are times when separate out-of-band documentation is appropriate, but that takes extra effort and can get out-of-date more easily.
2. Promote an it’s still okay to ask culture in parallel with the high-documentation culture. Asking questions in Slack can be a shortcut to finding the right document or finding out something is yet undocumented, and should be encouraged especially if the asker has already done a quick search without locating the needed information.
1. Promote self-documentation as much as possible—e.g. meeting notes typed straight into Google Doc, discussions typed straight into Slack, issues typed straight into GitHub, comments typed straight into code—so you’re documenting as you go in a way that’s automatically archived and searchable for future reference. There are times when separate out-of-band documentation is appropriate, but that takes extra effort and can get out-of-date more easily.
2. Promote an it’s still okay to ask culture in parallel with the high-documentation culture. Asking questions in Slack can be a shortcut to finding the right document or finding out something is yet undocumented, and should be encouraged especially if the asker has already done a quick search without locating the needed information.
i personally can't retain any information in meetings, and i've honestly watched meeting recordings back to take notes on important info that i totally glazed over at the time. this wastes a total ~121 minutes on average, based on their estimate of time it takes to refocus after meetings.
I love the idea of less meetings and more documentation, but I've never seen it work. Here's a few observations...
a. you need a person who "curates" the documentation, otherwise it completely loses organization quickly
b. things become out of date fast and it's not clear if you're reading something out-of-date
c. people write too much, meaning - things turn into this huge long form internal article and people get exhausted in just reading through it. Writing is actually quite hard.
I don't have a better solution/approach to recommend (besides having a curator), but the "less meetings / more documentation" train always seemed oversold to what I've experienced first hand.
a. you need a person who "curates" the documentation, otherwise it completely loses organization quickly
b. things become out of date fast and it's not clear if you're reading something out-of-date
c. people write too much, meaning - things turn into this huge long form internal article and people get exhausted in just reading through it. Writing is actually quite hard.
I don't have a better solution/approach to recommend (besides having a curator), but the "less meetings / more documentation" train always seemed oversold to what I've experienced first hand.
I don't think these means that documentation doesn't work. It means that while documentation works, there's a number of additional issues that you also have when you use documentation. Try having no documentation instead of disorganized or outdated documentation. I'll take the latter.
I love the idea, but we should be taking pinches from our fancy sea salt. Tremendous has less than a hundred employees. Just small enough that people can probably individually track the complete state of their respective arm of the business.
Marvelous is also about to face a significant stress test with the holiday season, both from retail usage of their product and from vacations of their employees. I wonder how routinely highly-documented the agendas will be when competitors start sniping their biggest clients as their service crashes from overcapacity.
Reversion to the mean is coming — what would be interesting would be to hear successful strategies to resist it.
Marvelous is also about to face a significant stress test with the holiday season, both from retail usage of their product and from vacations of their employees. I wonder how routinely highly-documented the agendas will be when competitors start sniping their biggest clients as their service crashes from overcapacity.
Reversion to the mean is coming — what would be interesting would be to hear successful strategies to resist it.
I tried to create this type of culture at my last gig, where I had the unusual privilege of being able to hire almost the entire engineering team, alongside my manager who was also very document oriented. Unfortunately, it didn't work out. Maybe Tremendous has done tremendously better, it's certainly possible, but here is a list of things that went wrong, maybe it's useful.
1. Standard interviews don't assess reading/typing speeds. If you want a high documentation culture this is critical. It took way too long for us to figure this out but many people in the company were significantly slower at reading/typing than us; they found long documents overwhelming and would find excuses to not read them. Slack conversations became a massive sore spot because unknown to us some people felt like they couldn't keep up. They'd try to type a question or response and we'd already posted another two paragraphs before they got a chance to finish their thought. They'd complain to each other that if they asked us a question they got back an essay in response, etc.
2. Documentation requires ownership, otherwise it rapidly becomes useless. Standard corp tooling like wikis doesn't make such workflows easy. They are however optimal from a corp politics perspective (dispersal of responsibility). Maintaining markdown based websites works well as long as you have empowered maintainers who view document quality as a core job function, but you have to force people to submit changes by e.g. rejecting at code review time changes that don't update the docs. People will moan. They will ask you to do it for them. They will submit absolutely min-viable docs changes, they will demand you hire technical writers even if they're easily capable of doing it themselves. And of course the moment you're not using a git-style workflow, just forget it, you have no chance of preserving coherency in any sort of knowledge base.
3. Lots of people aren't just slow but actively HATE reading and writing. They will make things up on the spot, or lie, or just flat out refuse to do the work rather than sit down and read a long document. Jeff Bezos has said about why Amazon uses meeting time to force people to read the memo:
"If we don’t, the executives, like high school kids, will try to bluff their way through a meeting"
You will have to fire people for refusing to read things if you're serious about creating and maintaining such a docs-oriented culture, which in practice is so unpleasant nobody ever does it and so maintaining such a culture is nearly impossible. You will also have to flat-out refuse to meet people in order to force them to read, because otherwise they'll receive a document and just ignore it. I had several cases where one of my most senior engineers would assert that a product we used didn't have feature X, and I had to correct him by pointing out that the user manual discussed feature X in detail. I knew this because I'd actually read the user manual cover to cover. Basically nobody does this and guess what, if you're the one person on the team who reads stuff then you're going to come across as the awkward smart alec who makes people look stupid. Sometimes, ignorance is bliss.
1. Standard interviews don't assess reading/typing speeds. If you want a high documentation culture this is critical. It took way too long for us to figure this out but many people in the company were significantly slower at reading/typing than us; they found long documents overwhelming and would find excuses to not read them. Slack conversations became a massive sore spot because unknown to us some people felt like they couldn't keep up. They'd try to type a question or response and we'd already posted another two paragraphs before they got a chance to finish their thought. They'd complain to each other that if they asked us a question they got back an essay in response, etc.
2. Documentation requires ownership, otherwise it rapidly becomes useless. Standard corp tooling like wikis doesn't make such workflows easy. They are however optimal from a corp politics perspective (dispersal of responsibility). Maintaining markdown based websites works well as long as you have empowered maintainers who view document quality as a core job function, but you have to force people to submit changes by e.g. rejecting at code review time changes that don't update the docs. People will moan. They will ask you to do it for them. They will submit absolutely min-viable docs changes, they will demand you hire technical writers even if they're easily capable of doing it themselves. And of course the moment you're not using a git-style workflow, just forget it, you have no chance of preserving coherency in any sort of knowledge base.
3. Lots of people aren't just slow but actively HATE reading and writing. They will make things up on the spot, or lie, or just flat out refuse to do the work rather than sit down and read a long document. Jeff Bezos has said about why Amazon uses meeting time to force people to read the memo:
"If we don’t, the executives, like high school kids, will try to bluff their way through a meeting"
You will have to fire people for refusing to read things if you're serious about creating and maintaining such a docs-oriented culture, which in practice is so unpleasant nobody ever does it and so maintaining such a culture is nearly impossible. You will also have to flat-out refuse to meet people in order to force them to read, because otherwise they'll receive a document and just ignore it. I had several cases where one of my most senior engineers would assert that a product we used didn't have feature X, and I had to correct him by pointing out that the user manual discussed feature X in detail. I knew this because I'd actually read the user manual cover to cover. Basically nobody does this and guess what, if you're the one person on the team who reads stuff then you're going to come across as the awkward smart alec who makes people look stupid. Sometimes, ignorance is bliss.
This is brutal, but sheds light on why my own documentation-heavy style doesn't catch on.
I get questions from people, which can be answered by searching my wiki and just finding the right page. I can see the number of pages visits with the wiki tool I use, so I am led to believe that I'd get a ton more questions if not for my wiki.
So what's the problem? I am just one person in my group. There's a couple hundred of us, and I don't think the next most documentation-heavy engineer is producing half of what I am. (Probably more like a quarter)
Which is a real shame. Part of why I produce so much documentation is that I've created by own tooling and processes which let me generate vast amounts of useful content on the fly, and quickly. I've got 100+ hours of dev work into one tool, and I'm pretty sure I'm the only user of that tool (although I give presentations on it from time to time). Think: A tool which looks up details about an environment, and then aggregates those details in markdown format (including links to dig in further). Copy > Paste > Save page > Done.
I get questions from people, which can be answered by searching my wiki and just finding the right page. I can see the number of pages visits with the wiki tool I use, so I am led to believe that I'd get a ton more questions if not for my wiki.
So what's the problem? I am just one person in my group. There's a couple hundred of us, and I don't think the next most documentation-heavy engineer is producing half of what I am. (Probably more like a quarter)
Which is a real shame. Part of why I produce so much documentation is that I've created by own tooling and processes which let me generate vast amounts of useful content on the fly, and quickly. I've got 100+ hours of dev work into one tool, and I'm pretty sure I'm the only user of that tool (although I give presentations on it from time to time). Think: A tool which looks up details about an environment, and then aggregates those details in markdown format (including links to dig in further). Copy > Paste > Save page > Done.
Does a README in every folder in a Github repo meet the requirements? What is the lowest friction way to do this?
Probably not IMO, it's very unlikely your source tree is structured the same way good docs should be. Docs are often task oriented, code is usually component oriented.
Ha, my tasks are usually updating those components. Mostly interested in developer efficacy. It is a real pain to find and reverse engineer components when starting a new gig. Would be nice to have an explanation and links to other components they interact with.
Sure. I tend to prefer a docsite generated using a rendering tool because when the docs look and feel high quality/high effort, people take it more seriously. But it can be that a README file in a set of directories is OK too. Chrome does this for example.
I didn't see anything about the hiring process needed to get high-documentation culture to work. Many developers don't write well. Some don't empathize with the reader and so can't communicate complex ideas effectively. Others lack the ability to abstract their ideas. Many will be coming from the exact opposite of a high-documentation culture and so simply will not value good documentation.
Asking people with poor writing skills to work in the way described here seems like it could lead to problems without a selection process favoring good writers, or at least a training system to get new hires up to speed.
Asking people with poor writing skills to work in the way described here seems like it could lead to problems without a selection process favoring good writers, or at least a training system to get new hires up to speed.
to many meetings -> not getting enough done -> hiring spree -> even more meetings -> reorgs to nowhere -> layoffs
1. If you want this culture, make it a rule, the way GitLab did with their Handbook-first Culture (https://about.gitlab.com/handbook/handbook-usage/#why-handbo...).
2. Do not expect anyone to do anything you have not trained them to do. If you want your employees to work this way, actually train them on how to do it.
3. Without leadership pushing this culture, it will. not. happen. Don't even suggest a change like this until you have sold at least 3 people in leadership.
2. Do not expect anyone to do anything you have not trained them to do. If you want your employees to work this way, actually train them on how to do it.
3. Without leadership pushing this culture, it will. not. happen. Don't even suggest a change like this until you have sold at least 3 people in leadership.
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'
I'm desperate for less meetings. How do you fight against Scrum? It seems like at some companies it's the only way they know how to "get things done", even if it doesn't really work
What about the low doc, low meeting culture
I'd like a read the code culture. For me documentation is harder to read than code and so inaccurate that you end up reading both anyway.
What is an example of that working? Just code that speaks for itself? How would you ever know why something was done?
Contrary to popular belief, it is almost always possible to express the 'why' (not just the 'what') via code, even if comments and/or external documentation are sometimes cleaner, simpler alternatives.
Turn around and ask. For small teams it might work well. Larger teams require more overhead, hence why hiring more people does not produce linear productivity growth.
You ask someone in slack. If that isn't sufficient, set up a small 1 on 1 meeting to discuss.
You can't avoid all meetings, but you can keep them few and small.
You can't avoid all meetings, but you can keep them few and small.
In long running projects, the people who know the answer may no longer be around.
Now my ability to find something is limited by someone else's availability, and everywhere I've seen this culture it's devolved into the same 1-2 people answering all the questions as not everyone has a built up map of who knows what.
After you are the 3rd person who contacted me for the same thing, the next one better read the fking documentation that I write.
I have had good experiences using commit messages for documenting the reasoning behind code changes.
it's a good start but it doesn't scale
Many in this thread seem to conflate documentation with code documentation, while I use it as a means to communicate requirements to the developers. Some mockups here, some data description there, it makes all the difference. Our stories/tickets increasingly consist of only a title, a wiki link and some acceptance criterions. Works great for me as a PO, devs like it and provides a lot more context than fragmented tickets do.
> 5 minute read
Either the author is some kind of reading savant, or this metric is way off. That's over 400 words a minute for a semi-technical persuasive essay, with multiple graphs.
I know there are marketing analytics out there saying that you must write everything in a 3-7 minute read band to maximize audience reach, but I don't think just telling people a long article is short is a good way to go about that.
Either the author is some kind of reading savant, or this metric is way off. That's over 400 words a minute for a semi-technical persuasive essay, with multiple graphs.
I know there are marketing analytics out there saying that you must write everything in a 3-7 minute read band to maximize audience reach, but I don't think just telling people a long article is short is a good way to go about that.
I think there is a trade off on amount of time spent on the high-documentation approach and how large you are. Totally makes sense for larger organisations but less so for startups. There is probably a number of consumers of the information produced at which point it makes the most sense to do go for 'high-documentation'. I wonder if anyone has done deeper research on this.
+1 for all docs being public-by-default.
But these are all sophisticated skills. And the broader industry does not reliably teach them.
ctrl-F "Training" 0 hits. ctrl-F "Hiring"
> But we take great care during the hiring process to choose people that thrive under these conditions.
Is the interview by post? There's a story here, but I don't know what it is.
ctrl-F "Training" 0 hits. ctrl-F "Hiring"
> But we take great care during the hiring process to choose people that thrive under these conditions.
Is the interview by post? There's a story here, but I don't know what it is.
I was recently introduced to www.Loom.com which is this fremium screen recording app and website (no affiliation). Being able to have a certain type of meeting asynchronously has been a boon to productivity. The async nature of texting is great and adding the same thing for audio and video/screen recording has been similarly great.
Personally, I do not like video recordings. I find them inferior to text communications in terms of maximum bandwidth and bandwidth to cost ratio (time to write and read).
However, some people are much better at communicating or understanding material if its shown visually, which can be much more time efficient for both parties sometimes. Every format has a place.
However, some people are much better at communicating or understanding material if its shown visually, which can be much more time efficient for both parties sometimes. Every format has a place.
Video recordings shouldn't necessarily replace written messages, they should replace video meetings.
If anyone who works there is reading this: There must be a spectrum of documentation-generating talent on staff. Have you ever had to read through the product of someone who isn't very good at writing it? How do you cope with mediocrity in that skill? (Is it sometimes cause to let someone go?)
This doesn't work at most companies because most people don't know how to type properly.
Thus they would rather speak at a meeting than type into a form, because they can speak several times faster than they can type.
I don't hire people who don't know how to type properly (or won't commit to learning).
Thus they would rather speak at a meeting than type into a form, because they can speak several times faster than they can type.
I don't hire people who don't know how to type properly (or won't commit to learning).
Here is my summary of the content of this piece: "We only hire introverts who like working in introvert ways. But we like to pretend that we are just normal people who have stumbled on a better way of working that has mysteriously eluded all the other smart people in the world."
All the corp document stores I’ve seen, and I think I’ve probably seen most of them by now, would benefit from a full-time librarian (or team thereof) and a help-desk to field enquiries. Because you have little hope of finding what you want, even if you know it’s in there somewhere.
is this the anti-agile manifesto? Personally, I think they got it right the first time (https://agilemanifesto.org/), even if most modern agile application feels pretty anti-agile today
Low trust, poor communication = low documentation, high meeting.
I work as a consultant with a lot of outsourced teams who poorly communicate or seem to avoid written responsibility.
really like that thought: "low-meeting culture allows us time to do high-value tasks"
I work as a consultant with a lot of outsourced teams who poorly communicate or seem to avoid written responsibility.
really like that thought: "low-meeting culture allows us time to do high-value tasks"
Is there any documentation system that incorporates an expiration date, forcing manual review to renew?
I also am interested in ways to tie source code and documentation together. For example: linking to methods in a way that follows refactoring.
I also am interested in ways to tie source code and documentation together. For example: linking to methods in a way that follows refactoring.
lol - (re: linking) ask and ye shall receive!
Show HN: CodeLink: create links to blocks of code in your IDE
https://news.ycombinator.com/item?id=33711480
Show HN: CodeLink: create links to blocks of code in your IDE
https://news.ycombinator.com/item?id=33711480
Any documentation I can't check into the git repo is useless to me.
It would be nice if instead of documentation, we could design things to be self evident. Feels like if you need to read the docs then the product/service failed to make it clear how to do something.
are your engineers evaluated on the quality and up-to-date-ness of the docs they produced? and are they paid more and promoted faster if they do produce quality docs?
if not, i don't believe you.
if not, i don't believe you.
Documentation should be atomic, not large pieces of text. And each atomic item has bidirectional dependencies to other atomic pieces or methods or classes or requirements or terms etc.
I work for a low-documentation, low-meeting company. It works great. We are routinely competing and winning against large international companies.
From my experience effective written communication and good comprehension are rare skills. That's the reason meeting culture is so resilient.
I thought high-documentation would be related to literate programming. Joke's on me, looks like we're going to try to reinvent LP forever.
Sounds like a great place to work.
Makes more sense for 100 people to read a doc and get the gist. Rather than interrupting the dev 100 times.
Makes more sense for 100 people to read a doc and get the gist. Rather than interrupting the dev 100 times.
Recently I've only worked for companies with limited (1 max) meetings for ICs a week, I definitely recommend it.
Is the lack of "meetings" offset by pair-coding, dragging out synchronous conversations in Slack, or otherwise controlling engineering time and schedule?
No, (currently) fully async as long as deliverables are met. The extent of 'controlled' engineering time is requiring 1x code review from a different SWE to merge a PR which is also async via GitHub comments.
Ahh nice! I was recently on the market and had nearly no luck finding a culture like that which matched my skill-set. I am envious.
It's still quite rare unfortunately, and there are still negatives: less time in meetings means more time actually working which isn't always what you want!
Though it's offset by very generous comp as there's not as much bloat to soak up your TC. So YMMV...
Though it's offset by very generous comp as there's not as much bloat to soak up your TC. So YMMV...
Most of documentation I've seen is either not yet finalized or already outdated. Often both at the same time.
Unless entire team is spending 2 days on docs every week, docs are hell. I prefer comments in the code.
Sounds like my current job which I love.
My last job, low documentation, low meeting. Basically every bit as bad as you might expect. Every job you basically have to figure everything out from scratch.
2 jobs ago, low documentation, high meeting. Daily meetings to discuss what I'm working on and how little the rest of the team is doing. Yet nothing changes or improves.
My last job, low documentation, low meeting. Basically every bit as bad as you might expect. Every job you basically have to figure everything out from scratch.
2 jobs ago, low documentation, high meeting. Daily meetings to discuss what I'm working on and how little the rest of the team is doing. Yet nothing changes or improves.
[deleted]
If only we could have an AI do the documentation...
[deleted]
[deleted]
Oh my god, that font.
My job is sweet.
The management really doesn't go in for meetings, especially not all-hands, nor 1:1s for us at the lowest level. We have onboardings and special messages and all those are recorded in case someone misses, it's no big deal.
Documentation: we have a master SOP document that's about a dozen pages, you can read it in an hour and understand it. There's a living spreadsheet that's updated so you have to check it on the regular. I've also helped build an aid for one particular investigative side, but it's optional. There's other documentation but it's all ancillary and optional, the biggest thing to know is SOP.
There's an #important-links channel on Slack and I do try to look through it on the regular, but all you really need to know is a small field.
We're all 100% remote, WFH team. We stretch from San Francisco, to NYC, to South Africa and coworkers in Australia too.
We're starting to branch out in non-English languages, so I'm sharpening my Spanish for the road ahead.
The management really doesn't go in for meetings, especially not all-hands, nor 1:1s for us at the lowest level. We have onboardings and special messages and all those are recorded in case someone misses, it's no big deal.
Documentation: we have a master SOP document that's about a dozen pages, you can read it in an hour and understand it. There's a living spreadsheet that's updated so you have to check it on the regular. I've also helped build an aid for one particular investigative side, but it's optional. There's other documentation but it's all ancillary and optional, the biggest thing to know is SOP.
There's an #important-links channel on Slack and I do try to look through it on the regular, but all you really need to know is a small field.
We're all 100% remote, WFH team. We stretch from San Francisco, to NYC, to South Africa and coworkers in Australia too.
We're starting to branch out in non-English languages, so I'm sharpening my Spanish for the road ahead.
As someone that hates taking a long time to write documents and has similar resistance to reading large technical documents I much prefer to ask my specific questions in meetings. I retain the information much better that way.
My experience with meetings is that they're effective at getting people to nod their heads and say they get it, but when it comes time to actually do something, they'll be back at the expert's desk needing to go over it again.
Then again, documentation doesn't necessarily solve that either, because then you have the people at your desk who don't read the documentation and need someone to walk them through it. But at least that way you don't have to go from memory.
Then again, documentation doesn't necessarily solve that either, because then you have the people at your desk who don't read the documentation and need someone to walk them through it. But at least that way you don't have to go from memory.
"Unfortunately, Tremendous is not available in the country where you are located. If this is a problem, please contact [email protected]."
I'm in Ukraine and this is disgusting.
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.