I think it's better to just continually verbalize any "core values" with your team as you go day-to-day. Thinking that you've written it down inside of an organized GDocs is not much different than having sent it via email (the location to retrieve it just changes).
* What’s being written down isn’t valuable, so people don’t trust the wiki to have valuable information and therefore ignore it.
* What’s being written down is valuable, but people have been trained to get information elsewhere and therefore don’t bother going to the wiki
I don’t really know how to address the former (“write better!” isn’t very actionable advice), but in my work I see the latter a lot, and the only way you can fix it is socially—if someone asks you a question that’s answered in the wiki, you have to tell them “read the wiki” instead of giving them the answer yourself.
People are lazy, and it’s almost always easier in the short term to just ask someone for the answer instead of looking it up yourself.
Having the information written down is important if nothing else than a source of reasoning going forward (people tend to remember do X but rarely why in my experience). However saying that asking a coworker is a bad thing is giving way too much credit to the documentation.
Additionally if you are talking about anything but the most basic associations talking with people is a good thing anyway as you can discuss your idea and see if there are problems the documentation couldn't tell you about because said problem would be listed in a different place.
- What permissions do I need to contribute code to this repo
- Where are the telemetry tables for X event
- Who’s the manager for project Y
- When will my commit make it into production
For the whys and hows that often warrant discussion, while I still think you should have basics documented (How do I add a new screen to this app, why do we call into this proxy service, etc) so that folks have a starting place, and then pursue actual discussion.
Even if the wikis are literally just the most basic associations, I still believe that would clear up a ton of repeated and honestly unproductive discussion time.
Good ops and code are usually to some extent self-documenting. If you had a wiki with 20 steps to perform some task, maybe the answer is that the process needs to be simplified.
Setting up MediaWiki and throwing it up on a Linode server costs 20 bucks a month and can be deployed from a Docker image in roughly 15-20 minutes. It can referenced by everyone, anyone can contribute to it with a full audit of changes, and it's easily searchable.
I use it to document technical and non-technical things like company policies, work flow processes, security practices, coding style, pretty much anything. New employees have a standardized on-boarding process that is clearly documented step by step for them to get setup with everything they need to start being productive by their second day of working here.
It's actually fairly low effort to do this and is a lot easier than having a bunch of people have to remember God knows what and when, or forgetting and then having to ask someone else who may have a vague recollection of it.
An authoritative source of knowledge that everyone has access to and anyone can contribute to is worth setting up.
Easily searchable on my machine with grep or ack or whatever you use. Many tools (such as github, many IDEs etc.) open it up with when you open up the project, including formatting it. If you really want, you can serve it up somewhere via HTTP. When something changes I can commit it right with the changes I'm making.
Our code style is also committed. As spotless configuration files, eslint configuration files etc. You can run these locally if you want to. Our CI/CD definitely runs them and fails the build if it doesn't pass. No exceptions.
The README.md I am speaking of is actually more than one README.md. We have more generalized ones dealing with "This is how to set up your dev env, so you can actually develop stuff", to more module specific ones like "this module is special from everything else in X, Y and Z".
That is absolutely not what we're talking about here though. If a project manager really wants to set up a local dev env for whatever reason, they can be my guest but don't expect me to tailor our whole everything around them and not my developers.
But then I remembered nothing takes 20 minutes. I'll bet it takes 20 minutes to set up the wikimedia server and then 4 days of Googling to get our single sign-on to work. We'll have to figure out what to do with backups. Plus we'll need to document the documentation process itself and do the painful change management with the organization. Finally, we don't use Linux, so it would probably take more than 20 minutes to figure this stuff out.
It's a great idea, but it's a non-trivial amount of work. Not that I disagree with your approach, but I'm saddened when I think about how to get there.
How exactly can you use an email (or email thread) buried somewhere as a part of onboarding process? How exactly can you improve that email when it shows as unclear/lacking info after you somehow managed to use it during onboarding?
1. It is easy to tell which documents are clearly marked as snapshots in time vs. living documents.
2. Most docs are snapshots, so people have enough energy to maintain the living documents.
3. There is a slack channel or team name on the living documents. That way, if you see something out-of-date and want to update it, you know where to ask.
It’s very rare you find an employee that’s purposefully malicious, at least in the early stages of a company (< 50 employees). Unless you have terrible character judgement.
If what you are writing down has value, and there’s no other way to obtain that knowledge, then people will use it.
This is a choice, not a fundamental law.
For example, I maintain a document that helps me keep track of bioinformatics files and some of their quirks (which files have two-line headers, etc). I do it for myself, but this information is also referred to by dozens of people in our group.