201–210 of 524 posts
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'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…
Try explaining that they can't push to the repo because they cloned the http URI and need to generate an RSA token and use SSH instead. Better yet, try to figure out that's the problem when they give you a totally unhelpful version of what the problem is.
Earlier quoted context omitted.
What is an example of that working? Just code that speaks for itself? How would you ever know why something was done?
You ask someone in slack. If that isn't sufficient, set up a small 1 on 1 meeting to discuss. You can't avoid all meetings, but you can keep them few and small.
Earlier quoted context omitted.
1. Paste image into assets folder. 2. Write . It's not that hard really is it.
Have you worked with non-technical teams, ever? Perhaps in teams of very young and gamer-type people this would work, but in any real world team I've been in, this would not in fact be easy unless there's a real time preview and a button you can click that auto-generates that snippet. People would forget the exclamation mark, mixup the brackets with the parenthesis, not know how to reference the right path to the ima…
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'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…
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…
I do get what you're saying because I struggled with it for ages. There are good GUI tools like Sublime Merge for easy conflict resolution now which would be one solution. I do think a web interface that just automatically commits by just adding your text in addition to the new text along with a warning would probably be the easiest solution and then just have someone edit it after the fact. It's not been my experien…
Earlier quoted context omitted.
1. Paste image into assets folder. 2. Write . It's not that hard really is it.
Have you worked with non-technical teams, ever? Perhaps in teams of very young and gamer-type people this would work, but in any real world team I've been in, this would not in fact be easy unless there's a real time preview and a button you can click that auto-generates that snippet. People would forget the exclamation mark, mixup the brackets with the parenthesis, not know how to reference the right path to the ima…
At the end of the day, if you've got someone who can't work out how to drag a file into a folder and then type  after you've shown them a couple of times, is this really the person you want writing the documentation for your process?
Earlier quoted context omitted.
We use Mark[1] to automatically create Confluence pages from Markdown documents in our git repos. So we can have a review process for documentation changes, the documentation of the code can be in the repo with the code, and yet it can still be accessed without having to give permissions to view the code repo! Helpful with a proprietary monorepo. [1] https://github.com/kovetskiy/mark
So simple an idea, it makes you wonder why it's not already a core feature in Confluence.
Earlier quoted context omitted.
That is indeed too technical. Try to explain how inserting an image is not just copy paste.
1. Paste image into assets folder. 2. Write . It's not that hard really is it.