281–290 of 524 posts
Earlier quoted context omitted.
In fact you lost non-technical people at Markdown.
Non-technical people used to learn bits of HTML just to get sparkly backgrounds on their MySpace pages. Markdown is absolutely masterable by anyone.
2. Do not expect anyone to do anything you have not trained them to do. If you want your employees to work this way, actually train them on how to do it.
3. Without leadership pushing this culture, it will. not. happen. Don't even suggest a change like this until you have sold at least 3 people in leadership.
Earlier quoted context omitted.
I 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?
What I find is that it's very "dumb", almost "... WHERE filename LIKE '%query%'" dumb. Example might be searching for " Technical Spec". - Can't find "Technical Specification" in the " " folder. - Can't find "Tech Spec" (and vice versa) - Can't find " " Is there some "enable real search functionality" checkbox I've missed, or am I just doing it wrong?
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.
1. Promote self-documentation as much as possible—e.g. meeting notes typed straight into Google Doc, discussions typed straight into Slack, issues typed straight into GitHub, comments typed straight into code—so you’re documenting as you go in a way that’s automatically archived and searchable for future reference. There are times when separate out-of-band documentation is appropriate, but that takes extra effort and can get out-of-date more easily.
2. Promote an it’s still okay to ask culture in parallel with the high-documentation culture. Asking questions in Slack can be a shortcut to finding the right document or finding out something is yet undocumented, and should be encouraged especially if the asker has already done a quick search without locating the needed information.
Earlier quoted context omitted.
So you're replaced something that's simple as paste in office documents with two separate steps, one outside the app requiring the user to navigate to the assets folder, and the second requiring remembering specific syntax.
“Stop, you were born with computers so you don’t notice it, but I’m not technical enough to paste an image in a Word document.” — The intern I just had to fire last month. She pretended because her generation was born with iPhones, that knowing advanced computer skills like Cmd+V was something that wasn’t a given at 21 years old. It blew my expectations about school - but at least school teaches them to find unexpect…
I think her assessment of the situation is fair.
Earlier quoted context omitted.
It's shocking how many people don't have the ability to organize their thoughts. I'm ashamed that I was completely guilty of this myself. At some degree of professional development in software, you start to verbalize things, so as to 'explain them to yourself' and it helps clear things up. This helped me understand that 'writing skills' (in this context) are frankly more matter of being able to organize concepts more…
It's funny how AI and humans struggle with similar issues of doing things intuitively and being unable to explain themselves.
You reminded me of a fun idea that I'll probably never do anything with:
Train an AI which is judged on its ability to quickly teach/train _another_ AI how to do the task. So, optimizing for ability to explain.
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…
> 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.
I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departme…
The answer is, of course: no. You just want it because it's familiar to you. Which is fine... if you were the only person using it.
Confluence is actually the best solution, hands down. It has a WYSIWYG. It supports Markdown. It has an API. It versions all content. It has fine-grained access control. It does not require granting a user access to a repo to write to a file. It has much more rich content to better convey information clearly to humans. It has full text search. Page management is simple (rename a page and it auto-redirects). And no other solution does all of this as easily or effectively.
The people who complain about Confluence simply don't care about use cases outside their own, and haven't taken the time to learn it. I am 100x more productive with Confluence than you are with Git and Markdown. And real people will actually be able to use what I've made there without learning complex tools or jumping through hoops.
Earlier quoted context omitted.
It's funny how AI and humans struggle with similar issues of doing things intuitively and being unable to explain themselves.
Yes! What's threatening about AI isn't that it's smarter than humans, but that it's cheaper and more scalable. And sometimes smarter. But usually a whole lot dumber. You reminded me of a fun idea that I'll probably never do anything with: Train an AI which is judged on its ability to quickly teach/train _another_ AI how to do the task. So, optimizing for ability to explain.
Earlier quoted context omitted.
I'm sure these are great technological answers but this problem can be solved simply and quickly by a human. Not every issue needs to be solved by a butter robot. Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?
> Why not employ a technical writer/documenter/whatever job title you like Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the quest…
I disagree, I've been apart of a few companies that have done exactly this. I would suggest not presenting this argument as an absolutism.