3 ms·

I've _never_ seen a wiki or internal documentation stay up to date. My experience has been to encourage public blogging / speaking of technical information. If

I've _never_ seen a wiki or internal documentation stay up to date. My experience has been to encourage public blogging / speaking of technical information. If its public, there are several benefits. First you need to explain to people with little context from the company. You also feel scrutiny to make it accurate and not embarrass yourself. And readers will see the date of authorship, and have a sense of when this information was true. And of course, Google is a better search engine than anything you'll have internally! For example, when I worked on search at Reddit, I didn't point people at anything internal (that stuff rots) but instead I would point people at places like: https://www.reddit.com/r/RedditEng/comments/1985mnj/bringing_learning_to_rank_to_reddit_search/ https://www.reddit.com/r/RedditEng/comments/1985mnj/bringing... https://www.youtube.com/watch?v=gUtF1gyHsSM https://www.youtube.com/watch?v=gUtF1gyHsSM The downside to this approach is companies are too precious about IP so don't want you to be specific. (despite it almost certaintly not being special). Also company blogs can get over-edited to the point where they lose authenticity in favor of SEO spam. This isn't the tool to use for things like runbooks, etc. It's a more useful thing for broader context. I wish more companies just gave their developers their own personal blogs, and were less precious about preventing speaking.

aljgz 1y ago
This is a very interesting take. At this moment, I have little hope that I can encourage others to do this in the short term, but a helpful reminder for myself to finish and post some of the drafts I've kept for too long.
- softwaredoug 1y ago
  At Reddit, I tried to be the instigator for other people to do this :) It helps to have someone encouraging blogging, speaking. Almost a team evangelist.
uaas 1y ago
Public speaking is great, but not sure if it’s easier to keep a recorded talk (or even a company blog post) up to date than anything else you have full control over.
- softwaredoug 1y ago
  I think the "keeping up to date" is a fools errand IMO. Because you end up with "half-up-to-date" documentation where someone thought to update some part of it, but not another. And it gets incoherent. So my preference is a coherent story at a point in time

aljgz 1y ago

This is a very interesting take. At this moment, I have little hope that I can encourage others to do this in the short term, but a helpful reminder for myself to finish and post some of the drafts I've kept for too long.

softwaredoug 1y ago
At Reddit, I tried to be the instigator for other people to do this :) It helps to have someone encouraging blogging, speaking. Almost a team evangelist.

uaas 1y ago

Public speaking is great, but not sure if it’s easier to keep a recorded talk (or even a company blog post) up to date than anything else you have full control over.

softwaredoug 1y ago
I think the "keeping up to date" is a fools errand IMO. Because you end up with "half-up-to-date" documentation where someone thought to update some part of it, but not another. And it gets incoherent. So my preference is a coherent story at a point in time