4 ms·

I'm that guy in my current company. When I get brought in to an existing project, the first thing I look for is the README. To my disappointment, it either does

I'm that guy in my current company. When I get brought in to an existing project, the first thing I look for is the README. To my disappointment, it either doesn't exist at all, it's the default generated, or it's 1 or 2 years outdated. So during project on-boarding, I document everything I can, create or update the README, then commit and push to the repo. In all of my coworkers across all projects, I'm the only one who does this. I'm pretty sure nobody reads them either. I don't mind though, it has paid for itself countless of times already, since I always reference it.

hpoe 5y ago
Honestly it is so frustrating for me when I have a new project that is written by someone on my team and I need to do something to it and so I go to view the repo in Github and everytime without fail there's never a stinking README.md and so I have to go message my coworker on teams and harass them to help me figure out things about the project that 10 minutes of writing some basic documentation could help.
xaner4 5y ago
I want to be that guy that document everything, because I have seen the need for system to be completely documented. however, every time I start to document some system or code the info change or I'm away from it for a small while and the documentation and the system drifts apart.
- Salgat 5y ago
  Exactly. Documentation is expensive and time consuming and needs to be maintained. They're absolutely great to have and can be vital, but it's up to management/leads to prioritize it because, at the end of the day, they decide where the money and man hours go.
  - cteiosanu 5y ago
    This. Good documentation could easily take much more time than an actual implementation of a feature / system and what is an initial X days/weeks/months of estimation is not swallowed as easily by (some) management when you tell them it should be doubled if quality documentation is desired.
jareklupinski 5y ago
there are dozens of us!
pwdisswordfish8 5y ago
> first thing I look for is the README. To my disappointment, it either doesn't exist at all, it's the default generated Auto generated READMEs (and their handcrafted equivalents) are worse than useless. Not only are you wasting your time creating one (and giving yourself the sense of having accomplished something when you haven't) but the effect of a README creation is one-to-many, so consider that wasted time and then throw a multiplier on it. That's the cost of a dummy README. Don't create them, people.
nickfromseattle 5y ago
Building a culture of documentation starts from the top. Today our 40 person org has 1,337 knowledge base articles (as of yesterday, a coincidence, and we probably have a different number today). It started with myself (CEO) creating all of the initial documentation. 3 months after my first employee joined, I started holding her accountable to creating and updating documentation. It's not a one time thing. You can't say, "your job is to do documentation" once. It's consistently talking about it. It's scoping in documentation updates and refreshes into bi-weekly sprints and quarterly goals. Once she was onboard, we began to hold everyone else in our organization accountable too. Again, it's never a one time thing to get anyone bought it. It needs to be constantly discussed and scoped. Today, all of the managers are bought in. Instead of me explaining the importance of documentation, it's our org's managers embodying and instilling the culture of documentation into everyone new. They understand the value of having their reports check the KB first. They understand the value of being able to link someone to a KB instead of repeating themselves. They understand the value of being able to work more async. They understand the value of not being a bottleneck for someone else. I stopped spending much time creating documentation about 6 months ago - and the number of documents just keeps increasing. Today, I'll push documentation forward for new position / roles. I'm working on delegating finance - and spent a bunch of time putting together documentation on how to handle the company's money. - Expense policies - Org software purchases - Invoicing and payroll - Phishing and security - etc
- deleted 5y ago
  [deleted]
hinkley 5y ago
When I was first sorting this out, I realized that I shouldn’t be repeating things from the documentation, I should just be linking to it. It’s a mixed blessing. In that case, the people who peppered us with questions slowly learned to find answers themselves. On the flip side when people ask you questions you get a better idea of what’s going on elsewhere in the project. Later though, when it turned out we had a bad batch of hard disks on our dev boxes, the setup docs went from pretty okay to complete.

hpoe 5y ago

Honestly it is so frustrating for me when I have a new project that is written by someone on my team and I need to do something to it and so I go to view the repo in Github and everytime without fail there's never a stinking README.md and so I have to go message my coworker on teams and harass them to help me figure out things about the project that 10 minutes of writing some basic documentation could help.

xaner4 5y ago

I want to be that guy that document everything, because I have seen the need for system to be completely documented. however, every time I start to document some system or code the info change or I'm away from it for a small while and the documentation and the system drifts apart.

Salgat 5y ago
Exactly. Documentation is expensive and time consuming and needs to be maintained. They're absolutely great to have and can be vital, but it's up to management/leads to prioritize it because, at the end of the day, they decide where the money and man hours go.
- cteiosanu 5y ago
  This. Good documentation could easily take much more time than an actual implementation of a feature / system and what is an initial X days/weeks/months of estimation is not swallowed as easily by (some) management when you tell them it should be doubled if quality documentation is desired.

jareklupinski 5y ago

there are dozens of us!

pwdisswordfish8 5y ago

> first thing I look for is the README. To my disappointment, it either doesn't exist at all, it's the default generated Auto generated READMEs (and their handcrafted equivalents) are worse than useless. Not only are you wasting your time creating one (and giving yourself the sense of having accomplished something when you haven't) but the effect of a README creation is one-to-many, so consider that wasted time and then throw a multiplier on it. That's the cost of a dummy README. Don't create them, people.

nickfromseattle 5y ago

Building a culture of documentation starts from the top. Today our 40 person org has 1,337 knowledge base articles (as of yesterday, a coincidence, and we probably have a different number today). It started with myself (CEO) creating all of the initial documentation. 3 months after my first employee joined, I started holding her accountable to creating and updating documentation. It's not a one time thing. You can't say, "your job is to do documentation" once. It's consistently talking about it. It's scoping in documentation updates and refreshes into bi-weekly sprints and quarterly goals. Once she was onboard, we began to hold everyone else in our organization accountable too. Again, it's never a one time thing to get anyone bought it. It needs to be constantly discussed and scoped. Today, all of the managers are bought in. Instead of me explaining the importance of documentation, it's our org's managers embodying and instilling the culture of documentation into everyone new. They understand the value of having their reports check the KB first. They understand the value of being able to link someone to a KB instead of repeating themselves. They understand the value of being able to work more async. They understand the value of not being a bottleneck for someone else. I stopped spending much time creating documentation about 6 months ago - and the number of documents just keeps increasing. Today, I'll push documentation forward for new position / roles. I'm working on delegating finance - and spent a bunch of time putting together documentation on how to handle the company's money. - Expense policies - Org software purchases - Invoicing and payroll - Phishing and security - etc

deleted 5y ago
[deleted]

hinkley 5y ago

When I was first sorting this out, I realized that I shouldn’t be repeating things from the documentation, I should just be linking to it. It’s a mixed blessing. In that case, the people who peppered us with questions slowly learned to find answers themselves. On the flip side when people ask you questions you get a better idea of what’s going on elsewhere in the project. Later though, when it turned out we had a bad batch of hard disks on our dev boxes, the setup docs went from pretty okay to complete.