9 ms·
My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated docu
by canucklady 4y ago
My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github. We've tried a bunch of search tools which successfully surface the million product documents, design documents, PM reports, planning docs, retro docs and standup and oncall notes related to any feature, none of which are up to date.
- sdflhasjd 4y agoIt's actually hilarious how Google - a company famous for it's search engine - made Docs, who's search function cannot find anything.
- crazygringo 4y agoI live and breathe using Google Docs search functionality. It's my main way of finding files scattered across 10 years of folder hierarchies. It works great. What do you mean it can't find anything?
- sdflhasjd 4y agoWhat I find is that it's very "dumb", almost "... WHERE filename LIKE '%query%'" dumb. Example might be searching for "<Cool Project> Technical Spec". - Can't find "Technical Specification" in the "<Cool Project>" folder. - Can't find "Tech Spec" (and vice versa) - Can't find "<CoolProject>" Is there some "enable real search functionality" checkbox I've missed, or am I just doing it wrong?
- crazygringo 4y agoYeah, I think you're "doing it wrong" as much as I hate to say that, sorry. Search is keyword-based, like large-scale search is pretty much anywhere. Expecting "specifications" to match "spec" is expecting too much, same as expecting half your search to match a folder and the other half to match a file the folder is in. The main thing to keep in mind is that search is content-based, not just filename. So instead, search for key terms you think are in the file, as opposed to focusing on folders/filenames. Start with one or two, then modify or add as necessary to narrow down.
- sib 4y agoTrue, although this is Google we're talking about and Google [web] search is smart enough to do a lot of statistically-driven NLU-type things on top of pure keywords... (I currently work at Google, but not in Search or Drive / Docs...)
- xapata 4y agoGoogle Photos search is magical.
- unnah 4y agoSo basically you have to search google docs like you used to search the web before google came along and revolutionized search?
- deleted 4y ago[deleted]
- anhner 4y ago> Expecting "specifications" to match "spec" is expecting too much When I use Google to search the whole web, it DOES match. So how come it doesn't work when I search a small document?
- mnd999 4y agoAnd it’s still miles better than Confluence.
- jumpei163 4y agoAre you using search feature in Drive? I've been using CloudSearch, which I heavily rely upon
- stirfish 4y ago> no documents about how to actually use the resulting software. Can all your engineers see all your other engineers' code? It's hard enough to get code to do what it says it does; I've very rarely seen documentation that's correct.
- commandlinefan 4y ago> 5 outdated documents describing the decision making process Would that place be the U.S. Department of Defense by chance?
- rfdave 4y agoNot if there's only 5 documents.
- akonbinator 4y ago
- futureproofd 4y agoDo we work for the same company? :P Confluence has been the bane of my attempts in finding any relevant docs. Which one is the source of truth? Which one was a draft written by an overly eager to make a first impression, new employee (who is no longer with the company)? Don't even get me started on saving meeting notes to confluence. These days, I maintain my own knowledge base on Obsidian. If there's ever any confusion or request for more information within the company, I copy-pasta the relevant note from my obsidian bank to whomever person or whichever confluence page they deem the source of truth.
- nopenopenopeno 4y agoDo you have any tips on how to maintain a developer's own knowledge base in Obsidian? I also use Obsidian but I currently use as more of a dumping ground.
- futureproofd 4y agoIt's actually quite simple even without using some of the advanced features: What I do is create a directory structure for each domain as I explore them. I.e. Toplevel: - Work -- Job A: -- Daily notes -- Services -- Auth --- overview --- login flow -- Client -- Logger -- Job B: -- Daily notes -- Architecture -- node -- react -- etc (edit: sorry about the formatting) As the scope of your work expands, you add another sub-directory or file where necessary. Once it starts to grow in size, you can start making insightful connections via [[keyword]]. Furthermore, you can pretty much take this knowledge base with you, wherever you go, by uploading the vault file to your google drive and accessing it locally via SMB. Automatic save/backup.
- neura 4y agoSo you are now the gatekeeper?
- whatshisface 4y agoIf an individual employee is going to put all that work in without being asked to or being given scheduled time to work on it they should get something in return.
- ebiester 4y agoI would suggest introducing two things. First, introduce The Diataxis framework ( https://diataxis.fr/ https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.) Second, I would introduct the idea of a Documentation Portfolio. I have a review of Agile Documentation at https://www.ebiester.com/documentation/2020/06/02/agile-documentation-takeaways.html https://www.ebiester.com/documentation/2020/06/02/agile-docu... and it speaks to another structure for how to build the documentation in a more reliable form and thinking more carefully about your audience for a particular type of documentation.
- c54 4y agoDiataxis looks interesting thanks for the link
- capableweb 4y agoWow yeah, it puts into much better words than what I've been trying to get software engineers to do for a decade or more. Really awesome resource, thanks again kind parent :)
- googlryas 4y agoThe nice thing about this as well is that, unlike a technical framework, you can start implementing many of the ideas of this framework without any sign on from the rest of your group. And if it works, what will eventually happen is people will say "wow, capableweb rights such fantastic documentation, we should go to them and ask for their advice on how we can all write documentation that good"
- crazygringo 4y agoDiataxis looks fantastic. That chart on the home page is absolute gold. Thanks so much for the link, I wish I'd had that chart ten years ago!
- 4y ago
- baby 4y agoSometimes (often?) an outdated document is still great and useful and much better than no documentation at all
- zeroonetwothree 4y agoEqually often it’s worse and a waste of time. And you won’t know which world you’re living in for a while.
- baby 4y agoI've yet to find an outdated doc that makes the situation worse (unless you assume it's correct and up-to-date, which you should never do with anything anyway). There's a reason we like RFCs even if they only represent a decision in time.
- triceratops 4y ago> Confluence There's your problem. The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.
- roflyear 4y agoYeah, I push back when people say "can you document that API you wrote in confluence?" It is such a stupid idea that it makes me question leadership. Some things are good to document there, but generally, if you're documenting code, you should do it in the code.
- Macha 4y agoI'd take confluence over google docs because of how bad Google Docs' search is surprisingly
- radicality 4y agoNot a fan of Google docs either, but I recently discovered CloudSearch which imo does a better job at searching Drive (and searches emails too, and few other places). link: https://cloudsearch.google.com https://cloudsearch.google.com
- l2silver 4y agoDo you mean searching within a document, or searching with google drive? I've found that google drive search is incredible, they've done a great job of indexing everything.
- Macha 4y agoThey have no content excerpts in search results, so it doesn't provide any help for finding which result is the one you want. It also weights titles incredibly heavy, which combined with the previous part led to me not even noticing it searched the document body for years.
- matwood 4y agoInteresting. Not that long ago we moved everything out of Confluence into Google Drive because GD search worked. Confluence search was horrible to find docs I knew were there.
- rqtwteye 4y agoI work in medical devices so we have to write a lot of docs. But they all disappear in document management systems where you can't find anything if you don't already know where it is. Are there no document management systems that are actually useful?
- contingencies 4y agogit works for us across business/electronics/electrical/mechanical/software. The exception is daily supply chain and accounting, which due to factors like urgency, multiple stakeholders per order, high pace of handover, external system integration, multilingual presentation requirements and nontechnical users we prefer a dedicated web based system with more of a real time focus with event hooks (eg. notification, translation, verification).
- rqtwteye 4y agoWhat kind of docs do you have in git? Git doesn’t work well with binary file formats like Word, Excel or Visio. You can do it but the diff won’t work.
- contingencies 4y agoMarkdown + .webp, mostly. Some 'TeX.
- wpietri 4y agoAsk yourself how many document management systems are selected after rigorous tests of actual usage vs those selected after sales presentations and schmoozing. That should give you your answer. And if that's ambiguous, then ask how often your company penalizes people for making the common but wrong choice versus the uncommon but wrong choice.
- rqtwteye 4y agoThis applies to pretty much all enterprise software. It’s rarely selected by or for the benefit of the actual users. Usually it’s selected for the benefit of management (for example reporting) or for friends of management.
- nelsonic 4y agoHaving multiple systems for docs and Slack for follow-up questions is a major red flag. What you’re describing is a billion dollar search product opportunity though. Most orgs don’t have the discipline to have a single source of truth. So you end up with this mess. Run! Or … fix it and then create a company to fix it for all the other orgs with similar data/docs siloes.
- pokstad 4y agoI don’t understand why more companies don’t just go all in on Slack as the interface to their knowledge base. There’s tons of integrations to enable it. Every place I’ve worked at with Slack has the standard 90 day retention policy in place which makes it impossible.
- coffeeblack 4y agoVery much my experience too. People need to actually learn how to write and maintain(!) documentation, otherwise it’s just a huge chaos. Rule 1: less (text) is more.
- ramesh31 4y agoThis is why I find documentation to be either useless or actively detrimental. Your documentation is the code. Unless you have a dedicated technical writer on the team whose full time job is to work with developers to document their code, it all just becomes an outdated confusing mess immediately. Obviously this doesn't apply to public facing codebases. But trying to keep an internal codebase documented, other than fully finished self contained library level code, is a sisyphean task.
- convolvatron 4y agothat's ok. but expect your onboarding to take a really long time.
- atom_arranger 4y agoAgree. If possible the documentation should live in / be generated from the code as well. I'm not checking confluence, write it in a ".md" file in the repo if you want me to see it.
- wpietri 4y agoI think it's important to realize that a lot of documentation is duplication. It duplicates something expressed in code, in configs, in structure, in people's heads, or in the real world. Duplication can be useful. But the more of it you have, the greater the maintenance burden is. (The main exception is documentation that is not supposed to be kept up to date, like a daily journal or blog posts.) So I think it behooves people to be very careful about adding documentation. Because as you say, it can turn 1 problem into n problems.
- gmd63 4y agoNo, code actualizes the intent of the documentation and the product. The natural language description of a product shouldn't need to be discarded in lieu of some machine language. The lingua franca of ideas is natural language.
- simmschi 4y agoFair enough, but you still end up with 2 separate ways to express things. And I have yet to see a company that changes the documentation first and then derives code changes from that. Usually tickets are written, code is changed. Updating existing documentation is an afterthought at best. Personally I prefer any formal or semi-formal documentation (e.g. Swagger) over a Confluence page any time of the day.
- wpietri 4y agoSure. But where some see the lack of updates as some sort of moral failure, I think it's usually a sign that there is a process problem. The documentation was supposed to solve some sort of problem, but the fact that people don't update it is usually a sign that either it wasn't a real problem, that documentation wasn't the right solution, or that there's a broken feedback loop in the team's process.
- hitchstory 4y agoI built this documentation/testing framework to do just that: https://hitchdev.com/hitchstory https://hitchdev.com/hitchstory I realized one day that the specs, tests and how-to markdown documentation I wrote all used the same examples. From that I derived the idea to create a "spec" DSL that could both be run as a test and generate markdown (with screenshots, etc.) to make nice high level how-tos. Cucumber has the same sort of idea but the DSL really isn't suitable.
- gmd63 4y agoLack of organization to that degree is an indicator of failed leadership
- Reimersholme 4y ago
- synu 4y agoYou really have to be religious about enforcing a single source of truth for any information and this gets a lot better.
- EFreethought 4y ago> you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github Are people at the same job telling you to check 3 different sources for internal docs? Maybe that is the main issue. Put knowledge in one place. More specifically: One place that is not Sharepoint.
- civilized 4y agoFrom my perspective, calling yourself a "high documentation" org leaves a similar impression as calling yourself a "high code" org.
- nonethewiser 4y ago> My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. How is this not inevitable if your goal is to always write things down? It seems like the way for document to be accurate is to keep the scope small and if you want everything in scope then it's going to contain a lot of outdated information.
- ghaff 4y agoYou basically need to deprecate and eventually probably take offline outdated docs. There's something to be said for the historical record but if it's indexed--and if it's not no one will probably find it--it's going to compete with current documentation for search. There's no easy answer.
- enraged_camel 4y agoLarge organizations in many sectors employ professional records managers for this reason (and many others). Every record has a “lifecycle” and it is deprecated and discarded after that.
- gautamdivgi 4y agoThere are docs and then there are Docs. I think documents should be treated as source code. Go through a proper PR process so that you know what the latest and greatest is. Maintaining a wiki is one of the worst ways to document. It just creates a sprawl that is hard to control. I deal with it on a daily basis but have had little success with getting my team moving to our source control system for documents.
- deleted 4y ago[deleted]
- znpy 4y agoWe might be colleagues then.
- scottlamb 4y agoYeah, that sounds horrible yet familiar. Regarding this part: > Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github. When I'm the person being asked and know of the doc in question, here's what I try to do instead: I ask where someone searched for it. Then I update that place to refer to the correct document (and do some light refresh on the doc as needed). This works whether or not they tried to look before asking. If they did, well, now the next person who does that will just find it. If they didn't, I'm making them look before getting an answer. Maybe they find it, maybe they don't, either way I'll help them in the end if they're willing to look.
- BurningFrog 4y agoEveryone wants accurate updated documentation. Nobody knows how to accomplish this. Whatever the solution is, if one exists, I'm sure it involves a lot of work keeping documentation up to date.
- TylerE 4y agoThey know how (documentation is embedded in/generated from code) they just don’t want to. Out of date doc is worse than no doc, because it makes you feel all warm and fuzzy right until you footgun.
- narrator 4y agoThe way I did this at a company I worked for is that we had a MediaWiki. That's the software that runs Wikipedia. Whenever anyone would ask me a question, I would make a MediaWiki page or add to an existing page and appropriately link the page or entry to other relevant pages and answer the question there. Then I would send them a link to the MediaWiki page. This was super efficient. Whenever any documentation was wrong, I would update it.
- dougk16 4y agoOne solution to this is to become an oracle at your company. Any time someone (namely someone higher in the company who is responsible for your pay) has a question, no matter how many times it's been asked, how recently it's been asked, how obvious and repeated it is in the documentation, you answer quickly and thoroughly, like a machine. After a year or two of this, you'll be able to ask for any raise, or to work remote, or to even switch to contracting. They won't want to lose you.
- jmspring 4y agoOne of the biggest issues with large companies is - there could be a lot of documentation- but can you find it. A lot comes from tribal knowledge/who to talk to/etc.
- satisfice 4y agoI will say the obvious: documentation sucks because good writing is a highly skilled activity that takes a lot of energy for most people to do, AND because keeping it up to date takes a lot of time, no matter how good you are at it, AND because leaders of companies don't want to spend ANY money on tech writers. That's it. No mystery. (BTW, this would also be why company financial records would suck, if management decided to save money on accounting staff and have all employees just kinda do their own accounting for the company. I SAY HIRE A SCRIBE FOR EVERY TECHNICAL TEAM!)
- bakuninsbart 4y agoIronically, it is much easier for me to write good documentation if there are a couple of meetings scheduled around it. Having 3 joint sessions with at least another person is great, first to get the "bone structure" of the document, then to confirm that the "flesh sits right", and finally to resolve any unclarities that might be left.
- brainsiq 4y agoIt sounds like you're describing something very similar to pairing (to write) and peer review on code, but for docs, rather than "meetings"?
- arendtio 4y ago> good writing is a highly skilled activity This. Yes, having everything written down and searchable is definitely a good goal. However, in my experience, the people in most companies have very different skills and few are good writers. So it probably takes a lot of time to create an organization that has a good process for creating great documents, let alone to transform an existing organization which can do so.
- hw 4y agoWhat many dont realize is that documentation is tech debt. You can spend a lot of time and write a lot of documentation and have to also spend time updating it. I have worked with teams that focus so much time on design docs and insist that everything has to be documented. Pace of work is slow. Documentation and designs became obsolete due to shutting down of services, change in architecture, refactors. The best form of documentation is code.
- tshaddox 4y agoI think it’s a bit odd to call it tech debt. I’d say something more like “documentation is part of your tech, and needs to be maintained like the rest of your tech.” It’s only tech debt if you decide to not maintain it.
- beckingz 4y agoAgreed. Documentation has upkeep costs as the software and environment change.
- dnsmichi 4y ago> The best form of documentation is code. Documentation as code might be a good alternative path, using the same tools and processes as software development and embed documentation tasks into engineering workflows. More insights in https://about.gitlab.com/blog/2022/10/12/five-fast-facts-about-docs-as-code-at-gitlab/ https://about.gitlab.com/blog/2022/10/12/five-fast-facts-abo... how the GitLab technical writing team collaborates. Note: GitLab team member here.
- jollofricepeas 4y agoExactly this. I think that high documentation can work BUT the company has to invest in it in the way that Digital Ocean or even Stripe has done outwardly. 1. Investment - You have to hire at least a few technical writers and librarians to provide training & cleanup functions. 2. Management buy-in - You have to budget for it and encourage it through day one communication (ie. New hire training) and consistently rewarding and recognizing people for getting it right.
- apatters 4y agoSo update the documents? I mean, you're clearly not describing a high documentation culture, you're describing a culture that underinvests in intra-organizational communication. I run a high documentation, low meeting culture by necessity (we operate in five time zones around world). Meetings vs docs is remarkably similar to the decision between paying for office space vs paying for occasional team retreats. If you run a fully remote company retreats are almost always a better use of your money than leasing office space. But you still need to pay for something. Similarly with meetings vs. process documentation. If you're heavily remote and spread out I'd say you should cut down on meetings and being high documentation is the better choice. But again you still need to "pay" for something - you save time on meetings but you need to reinvest at least part of that time into writing documents. Another bonus of documents is that they scale better than meetings. McDonald's doesn't deliver the same big Mac in every corner of the world by holding a lot of meetings. They have a book that goes out to all of their thousands of franchisees. When they want to add another thousand franchisees, they print more books. If the documents are out of date my answer to my team is always "update them!" Anywhere that we're writing documents there are revision and discussion features so it's not like you can irrevocably screw something up, just improve it and let us know what you did. I do struggle with getting people to actually do it though.
- xlix 4y agoThis sounds so similar to my new place of employment, it has to be the same.