4 ms·
I like how you gloss over documentation as if it’s not even a viable solution. Documentation isn’t hard to generate. Set up a wiki so you can document things t
by philwelch 9y ago
I like how you gloss over documentation as if it’s not even a viable solution.
Documentation isn’t hard to generate. Set up a wiki so you can document things there, move your internal “how do I do X” chatter from Slack to email lists and maybe a StackExchange installation, and you end up with multiple indexable, searchable sources of long-form documentation.
Sometimes, documentation is work. So do the work. People and organizations who avoid that kind of work and say “just use Slack” end up trading 1,000 hours of interruption over 1 hour of work.
- llimllib 9y agoEverywhere I've ever worked, "set up a wiki" has meant "create something once that nobody ever remembers the existence of"
- philwelch 9y agoBecause writing the documentation is work and seems hard so people don’t do it.
- deleted 9y ago[deleted]
- ebiester 9y agoOr, it accumulates so much cruft that it's hard to find the valuable information. I think there's room for documentation librarians, whether by role or job title, but it's hard to justify the expense in smaller organizations.
- ivan_gammel 9y agoIt's a trained skill - everyone can be a librarian in the team.
- ebiester 9y agoOne person needs to lead the standards and the organization or the conflicting opinions will drive it apart. The librarian is a role, but that doesn't absolve the rest of the team from following the librarian's lead.
- protomyth 9y agoI found that a bit of scripting will make a wiki a bit more maintainable. Replace pages that are out of date with a tag of some sort (e.g. #outdated). Have a script spider the wiki from the home page and send out an email with all the reachable pages with tags. Either fix the page or make sure it’s no longer reachable.
- ghthor 9y agoPro librarian work right here, Nice work!
- davidbanham 9y agoIn my experience, documentation stored in source control alongside the code gets updated and maintained. Documentation stored in a wiki is left to rot.
- philwelch 9y agoFor code documentation, that's definitely true, but you need places to document processes, designs, and other things like that.
- carlmr 9y agoOut of sight out of mind is one component of this. The other is how easily you find the documentation. Most people are willing to document if it's easy to do so, and most people will read the docs if they're easy to find.
- dingo_bat 9y agoAlso, nobody can ever find again, even if they remember. And then they will create a whole new page for the same thing plus a small addition. Then 6 months later some poor soul will notice that you have 10 pages on how to do X and he will delete everything and consolidate them all into one page. Then the cycle begins again. Wikis are fucking useless.
- user5994461 9y agoEverywhere I've worked with wiki, I found that people actually read the wiki and that it contained both important guides for new users/developers/maintainers and old documentation that was crucial for old systems.
- mvindahl 9y agoThe last three corporate wikis that I have worked with have tended to contain some very useful and well maintained sections detailing stuff like developer machine setup and tooling. They have also contained large amounts of information from separate projects, none of it which was relevant to my task at hand, and on top of that they have contained a wasteland of obsolete pages, the contents of which was trusted by no one. I don't have a problem with the concept of a Wiki per se but I do have issues with treating them as a magical virtual haystack on top of which you can shovel information and from the midst of which you can painlessly extract needles.
- user5994461 9y agoBetter have a wiki with some obsolete pages than have nothing and no documentation at all.
- mvindahl 9y agoTrue dat. Writing no documentation is also a bad path. Personally I've come to favor keeping the technical documentation close to the code. That is, keep it as markdown files and check it into git. They are just as easily hyperlinked to as a wiki page on the bitbucket web interface (or whichever system is used). The main README.md should contain information on how to set up the dev environment. Other README.md files, located in the folder root of modules, provide more specific information. Documentation of a less technical nature may still find a natural home in the Wiki, since we also need a place where various managers, testers, salespeople, support people, etc. can maintain their documentation.
- ebiester 9y agoI swear there's a startup in there... I have some ideas to combat it. It will probably rattle in my brain for another year until someone has already come up with a "good enough" solution and I'll lament that I didn't go for it. (Life circumstances have me away from the startup life at the moment.)
- quacker 9y ago> move your internal “how do I do X” chatter from Slack to email lists and maybe a StackExchange installation, and you end up with multiple indexable, searchable sources of long-form documentation. Really, those stores of "long term" documentation complement chat rather than replace it (whether it's Slack, IRC, or whatever). Over time, you should be developing that documentation, so when you have repeated "how do I do X" type of questions in chat, you can often direct people straight to the docs. But documentation is never foolproof. It's inevitably incomplete, it goes out of date, etc. And for the information that the docs don't cover, you want a real time asynchronous discussion that's not as heavy-weight as a meeting or as slow as email, which is a good fit for chat.
- philwelch 9y agoChat is many things, but “asynchronous” is not often one of them.
- quacker 9y agoChat is absolutely asynchronous. It supports synchronous discussion, but I specifically like chat because I can ignore it until I dedicate a few minutes to look through the notifications.
- TeMPOraL 9y agoYou're lucky then. IMs are by their design pretty asynchronous, but there is this common dysfunction in many organizations - expecting you to be constantly on the chat and participate in real-time. That's the organization turning an asynchronous tool into a synchronous one, true, chats tend to facilitate that dysfunction much more than e-mail.
- ebiester 9y agoIn my experience, it's chat that drives the documentation.
- ebiester 9y agoMy personal experience is that the people willing to answer the questions on slack are also the ones who take those answers and put them in documentation so they don't have to keep answering the same questions. My experience is also that those who don't bother to be responsive to questions aren't pained enough to write the documentation. Further, due to the blindness of expertise, they document the wrong things. It's precisely the pain of interruption that leads to empathy and good documentation. My team, as one who sources multiple teams, does a significant amount of work in documentation precisely because we know the pain points. I had a pain point recently when some behavior changed that broke a consumer. I could track to the change, but I couldn't tell why because this person didn't make a meaningful git commit. They didn't create a changelog that explained neither the technical changes nor the product rationale. So, off to slack, and waiting because someone was "too busy" to do any of this. I have an idea that teams should have a "slack on call" person who rotates daily to interface with other teams. This means that one person is impacted every couple of days. It sort-of works in practice.
- philwelch 9y agoI’m not dogmatically opposed to chat, or helping people, or anything like that, and I’ve seen much the same dynamic at play. My problem is more with the culture that arises when conversations move from email to Slack, when interrupting people becomes the preferred mechanism over RTFM, and when I can’t do a goddamn thing without a chat app pinging me because someone @here’d a channel I’m in with something I can’t help with. Basically, I miss long-form written communication. Slack and PowerPoint are tools that destroy that.
- icelancer 9y ago>> Basically, I miss long-form written communication. Slack and PowerPoint are tools that destroy that. Only if your business allows them to be. We use Slack with specific reasons on how it should be used, with Basecamp as the documentation/project management layer. Slack is not meant to be abused like it is in the article, and the fact that people do it like that isn't a fault of the tool.
- watwut 9y agoToo many developers simply refuse to do documentation or half-ass it. Developers who write good documentation are not valued or rewarded by companies and teams. Instead the teams grows to expect them to do all of it (while also considering them lesser because they don't do less cool stuff). Hence complete circle. Unfortunately, not documenting seems to be part of culture.