261–270 of 524 posts
All developers should spend time working in support. That time will make them appreciate the incredible power and utility that documentation provides to everyone...including your future self.
Earlier quoted context omitted.
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?
Ask 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.
Earlier quoted context omitted.
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?
git 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, tra…
Earlier quoted context omitted.
I would suggest introducing two things. First, introduce The Diataxis framework ( 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 Portfo…
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?
Earlier quoted context omitted.
No, (currently) fully async as long as deliverables are met. The extent of 'controlled' engineering time is requiring 1x code review from a different SWE to merge a PR which is also async via GitHub comments.
Ahh nice! I was recently on the market and had nearly no luck finding a culture like that which matched my skill-set. I am envious.
Though it's offset by very generous comp as there's not as much bloat to soak up your TC. So YMMV...
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: >…
https://discuss.codemirror.net/t/implementing-wysiwyg-markdo...
What about the low doc, low meeting culture
What is an example of that working? Just code that speaks for itself? How would you ever know why something was done?
Earlier quoted context omitted.
> I know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writin…
In fact you lost non-technical people at Markdown.
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…
> I know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writin…