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.
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?
Thanks so much for the link, I wish I'd had that chart ten years ago!
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.
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.
There's your problem. The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.
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.
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.
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.
That describes Sharepoint more than 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.
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!)
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.
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.
The lingua franca of ideas is natural language.
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.
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.
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.
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.
> 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.
What do you mean it can't find anything?
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.
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.
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).
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.
Out of date doc is worse than no doc, because it makes you feel all warm and fuzzy right until you footgun.
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.
There's no easy answer.
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.
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.
I'm not checking confluence, write it in a ".md" file in the repo if you want me to see it.
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.
A lot comes from tribal knowledge/who to talk to/etc.
People need to actually learn how to write and maintain(!) documentation, otherwise it’s just a huge chaos.
Rule 1: less (text) is more.
Would that place be the U.S. Department of Defense by chance?
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.
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.
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.
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.
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.
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?)
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.
How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?
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.
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.
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:
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.
2. Write .
It's not that hard really is it.
The fact you need one person technical enough to resolve conflicts is already a deal breaker.
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 least you will have multiple revisions.
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).
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.
- 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 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 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.
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".
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.
Unless of course there's a good reason for maintaining your docs in markdown files, but all of them?
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..
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 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.
We also encourage bullshitting in everyday communications. It drives me nuts.
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)
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.
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 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.
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.
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.
Pun intended?
So I just write crap as well.
Why does everyone else has to pay the insane price for that?
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.
I've seen it a number of times in my career.
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.
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.
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.
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...
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...
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/
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...
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.
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.
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)
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"
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 understand it both ways.
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
One can only dream everything had documentation as great as i3wm's as a bare minimum.
But it's better to know than to be ignorant, usually.
Oh god yes! This - a thousand times this !!
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.
*SmoothScroll*$script-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)
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.
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.
Easy to use, desktop app, search, and crucially highlights new changes and additions so you can see something is updated
That's quite a load-bearing "just" there.
A long provisioning instruction became much shorter as a result of automating it by reducing the need to document.
>In a document, the content is all you have. It forces people to focus on communicating their ideas as clearly as possible.
But I worked for a Japanese corporation, so we had regularly-scheduled meetings. I was able to reduce them, though.
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.
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.
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.
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.
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.
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".
That probably depends on how you prioritize it. You can dictate that the docs (and the tests) be written before features are added.
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.
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.
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.
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.
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.
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.
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.
You can't avoid all meetings, but you can keep them few and small.
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.
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.
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.
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).
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 also am interested in ways to tie source code and documentation together. For example: linking to methods in a way that follows refactoring.
Show HN: CodeLink: create links to blocks of code in your IDE
if not, i don't believe you.
Makes more sense for 100 people to read a doc and get the gist. Rather than interrupting the dev 100 times.
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.
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.
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.
I'm in Ukraine and this is disgusting.