291–300 of 524 posts
Thus they would rather speak at a meeting than type into a form, because they can speak several times faster than they can type.
I don't hire people who don't know how to type properly (or won't commit to learning).
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…
So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopeless?
PS: to solve the second loss/discovery part, I think we are heading for that AI powered simple "unified search" experience.
Earlier quoted context omitted.
Sometimes (often?) an outdated document is still great and useful and much better than no documentation at all
Equally often it’s worse and a waste of time. And you won’t know which world you’re living in for a while.
Earlier quoted context omitted.
> 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.
I'd take confluence over google docs because of how bad Google Docs' search is surprisingly
Earlier quoted context omitted.
I do agree that an online google doc style WYSIWYG markdown solution would be preferable for non technical and then git and markdown for technical would be the ideal solution.
My sense is the markdown/git/render a documentation wiki with mkdocs is mostly solved. The issue is having that easy interface for non-tech folk. And related to this is the state of WYSIWYG markdown editing. The Basecamp folks created the very polished Trix rich-text drop-in which is a replacement for TinyMce, which while the standard seems to carry issues. Basecamp explained the issue with most approaches as such: >…
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.
I'm going to take a slightly different interpretation of your comment because I think it's an interesting discussion: are the non-technical people of today less technical than the non-technical people of the MySpace days?
From what I have observed, I would say yes. If you took the bottom 10% of users back then, you might have a hope of teaching them HTML. Today? No chance. In particular I think "willingness to learn anything" has really waned.
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…
I 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?
You may still not know how to find anything, but they will.
Like a lot of other things, this has suffered from computerization making it yet another small part of everyone's job (which also increases context switching, the amount of shit you need to know and keep track of, and generally makes jobs more stressful) rather than a specialty that's the main focus of a few workers.
The benefit (get to stop paying some employees) is easy to measure, while the harm is not.
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…
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.
Earlier quoted context omitted.
> 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 accu…
You 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.
Earlier quoted context omitted.
Not really because if you're using Obsidian you can just copy paste images and it will handle the syntax and moving the asset into the correct location anyway. But is taking an hour to read through a markdown cheatsheet really the worst thing in the world if what you end up with is far more useful and maintainable documentation? Seems like a pretty big pay off for not a lot of staff training.
> But is taking an hour to read through a markdown cheatsheet really the worst thing in the world if what you end up with is far more useful and maintainable documentation? This makes no sense given that you get the same payoff by using something like Atlassian's wiki. No git, no markdown, none of this nonsense, users can just immediately hit the ground running with advanced formatting support and version history. I…
Except that like all WYSIWYG editors, Confluence's editor is buggy and unpredictable. You can only use it in a browser. Because it doesn't even have a 'raw' editing mode anymore, you can't work around the WYSIWYG editor when it's broken. Uploading or converting to it from external sources is a PITA, when it's even possible.
If you want technical documentation that developers are going to maintain, it has to be a joy to work with in their own editors.
WYSIWYG isn't actually better. It's a broken paradigm, and that's why every single attempt to move Wikipedia over to a WYSIWYG editor has failed.