4 ms·

I respectfully disagree to an extent. I think most/all documentation ends up rotting and being ignored. If you take the time to write it down, it doesn't mean t

I respectfully disagree to an extent. I think most/all documentation ends up rotting and being ignored. If you take the time to write it down, it doesn't mean that others will take the time to read it or refer to it. 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).

carbocation 6y ago
Not really a general counterpoint, but I do think that if documentation is concise and useful enough so that stakeholders keep it up to date, it can work. 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.
Kranar 6y ago
This might be fine at a smaller company, but as you grow, having people verbalize these things results in slight variations that over time grow into very big inconsistencies. 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.
- tharkun__ 6y ago
  Why would I want something like that on an external resource like a wiki? What's wrong with having it right there in the source in a README.md? 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.
  - Kranar 6y ago
    I assume you're referring specifically to the coding style document rather than the host of things that a company should document. The advantage of having the coding style documented in a format that supports some kind of markup over a plain text file is to support syntax highlighting, searching/indexing, cross referencing other documents, including diagrams and a host of other features that plain text files lack support for.
    - tharkun__ 6y ago
      You should not assume and I should have specified more clearly. 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".
  - GSGBen 6y ago
    This works for developers but excludes large swathes of other stakeholders, some with huge amounts of business/process knowledge. MediaWiki supports WYSIWYG via VisualEditor, which increases usage from others (and has the benefit of making tables much more pleasant to work with).
    - 6y ago
keithnz 6y ago
from years of doing wiki documentation, document rot is fine, if it rots, so be it. Most of the time I write the docs for me but with a "getting started" frame of mind. On our wiki there are a whole bunch of actively maintained pages now that were initially seeded by myself or other devs, and there's a bunch of dead pages which are occasionally very useful , some of it is horribly dead. But the active pages are great, they save everyone time. Main thing is to not invest vast amounts of time to the docs, don't spend time drawing diagrams unless its a photo of a quick hand drawing, and just put in more effort as things prove useful
y2bd 6y ago
There are two ways that I interpret this * 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.
- Guvante 6y ago
  If we get better search systems I would be totally on board. But most knowledge base systems have a hard time finding similes for words let alone sorting articles containing multiple keywords in a useful order. 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.
  - y2bd 6y ago
    Sure, I should make clear: documentation/wikis are best for who/what/when/where of things like - 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.
ska 6y ago
> I think most/all documentation ends up rotting and being ignored. This is a choice, not a fundamental law.
ryanSrich 6y ago
I think this is all cultural. Smart employees want to do good work. If you aren’t providing them with the context and knowledge to do that work, then you’re failing. If your documentation isn’t useful, that’s your fault. If no one cares about the roadmap and couldn’t even tell you what’s on it, that’s your fault. 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.
jskrablin 6y ago
Documentation that ends up rotting and being ignored is usually a consequence of a poor organization/processes. Such places are usually not a very happy place to work at. 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?
- afarrell 6y ago
  Documentation rotting is fine so long as: 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.
nonford150 6y ago
Documented processes, shared and practiced on a daily basis become habits, which are then passed on to new members of the team. are an invaluable method of training and stability.

carbocation 6y ago

Not really a general counterpoint, but I do think that if documentation is concise and useful enough so that stakeholders keep it up to date, it can work. 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.

Kranar 6y ago

This might be fine at a smaller company, but as you grow, having people verbalize these things results in slight variations that over time grow into very big inconsistencies. 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.

tharkun__ 6y ago
Why would I want something like that on an external resource like a wiki? What's wrong with having it right there in the source in a README.md? 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.
- Kranar 6y ago
  I assume you're referring specifically to the coding style document rather than the host of things that a company should document. The advantage of having the coding style documented in a format that supports some kind of markup over a plain text file is to support syntax highlighting, searching/indexing, cross referencing other documents, including diagrams and a host of other features that plain text files lack support for.
  - tharkun__ 6y ago
    You should not assume and I should have specified more clearly. 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".
- GSGBen 6y ago
  This works for developers but excludes large swathes of other stakeholders, some with huge amounts of business/process knowledge. MediaWiki supports WYSIWYG via VisualEditor, which increases usage from others (and has the benefit of making tables much more pleasant to work with).
  - 6y ago

keithnz 6y ago

from years of doing wiki documentation, document rot is fine, if it rots, so be it. Most of the time I write the docs for me but with a "getting started" frame of mind. On our wiki there are a whole bunch of actively maintained pages now that were initially seeded by myself or other devs, and there's a bunch of dead pages which are occasionally very useful , some of it is horribly dead. But the active pages are great, they save everyone time. Main thing is to not invest vast amounts of time to the docs, don't spend time drawing diagrams unless its a photo of a quick hand drawing, and just put in more effort as things prove useful

y2bd 6y ago

There are two ways that I interpret this * 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.

Guvante 6y ago
If we get better search systems I would be totally on board. But most knowledge base systems have a hard time finding similes for words let alone sorting articles containing multiple keywords in a useful order. 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.
- y2bd 6y ago
  Sure, I should make clear: documentation/wikis are best for who/what/when/where of things like - 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.

ska 6y ago

> I think most/all documentation ends up rotting and being ignored. This is a choice, not a fundamental law.

ryanSrich 6y ago

I think this is all cultural. Smart employees want to do good work. If you aren’t providing them with the context and knowledge to do that work, then you’re failing. If your documentation isn’t useful, that’s your fault. If no one cares about the roadmap and couldn’t even tell you what’s on it, that’s your fault. 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.

jskrablin 6y ago

Documentation that ends up rotting and being ignored is usually a consequence of a poor organization/processes. Such places are usually not a very happy place to work at. 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?

afarrell 6y ago
Documentation rotting is fine so long as: 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.

nonford150 6y ago

Documented processes, shared and practiced on a daily basis become habits, which are then passed on to new members of the team. are an invaluable method of training and stability.