5 ms·

> 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. Gi

> 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. Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people.

rcarr 4y ago
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 experience that there's a hell of a lot of merge conflicts going on with documentation anyway but I could see how it could happen if you had multiple non technical people actively working on a project. Another not great but possible solution could be for non technical people to work on something like a Google Doc when stuff is in highly active development and to then copy this to a markdown document later when its solidified. I do think that as a society we have to start looking at stuff like this as a new essential skill though. We wouldn't expect people to be working without basic literacy, numeracy and computer skills and I think we are going to have to start looking at upgrading our sense of what basic computer skills entails to include stuff like git and teaching it in schools from an early age.
- jonwest 4y ago
  GitHub does offer the ability to modify files within the web UI and open a PR from there.
- remus 4y ago
  I think even the idea of merging changes is a step too far for all but the most technical users. Most user's idea of what it should look like start and end at a word-like UI, so having to introduce the idea of merging different copies together and resolving conflicts is too far outside that view. In my opinion this is why Google docs has become popular because it solves that tricky problem of having to think about how your edits interact with someone else's.
  - rcarr 4y ago
    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.
    - bpicolo 4y ago
      I'm technical and I still prefer WYSIWYG for writing documents. I want it to be easy for me to pull in rich content (images, info boxes, column formatting) It's ok to be technical and not enjoy markdown, heh.
    - evolve2k 4y ago
      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: > Most WYSIWYG editors are wrappers around HTML’s contenteditable and execCommand APIs, designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, and eventually reverse-engineered and copied by other browsers. > Because these APIs were never fully specified or documented, and because WYSIWYG HTML editors are enormous in scope, each browser’s implementation has its own set of bugs and quirks, and JavaScript developers are left to resolve the inconsistencies. > Trix sidesteps these inconsistencies by treating contenteditable as an I/O device: when input makes its way to the editor, Trix converts that input into an editing operation on its internal document model, then re-renders that document back into the editor. This gives Trix complete control over what happens after every keystroke, and avoids the need to use execCommand at all. Unfortunately Trix does not render markdown so can’t be used in a markdown documentation workflow. Has anyone seen a decent implementation of WYSIWYG for markdown that has the necessary polish to be non-tech friendly?
      - rcarr 4y ago
        I believe Obsidian are using ProseMirror or CodeMirror, the logo is at the bottom of CodeMirror so I assume it is the latter. There was this forum post from one of the Obsidian team a few years back asking about it https://discuss.codemirror.net/t/implementing-wysiwyg-markdown-editor-in-codemirror/2403 https://discuss.codemirror.net/t/implementing-wysiwyg-markdo... https://codemirror.net https://codemirror.net https://prosemirror.net https://prosemirror.net
joegahona 4y ago
> Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people. How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?
- vasco 4y ago
  Most of the issues with Confluence I've seen are lack of organisation, out of date information mixed with up to date pages and really poor search / discoverability. The fact that people can just edit or create a page at any point is one of the better parts because it's easy for someone to fix something up during onboarding, during a drive-by consultation etc.
  - bratbag 4y ago
    Even poor discoverability can be fixed with labels. But yes, the out of date info is a killer.
- otikik 4y ago
  Google Docs
- WorldMaker 4y ago
  There are Wiki-like interfaces for git+Markdown: GitHub's wikis, gitit, and more.
nonethewiser 4y ago
> 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 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.
- carom 4y ago
  Or just download Github Desktop onto their machine and show them how to use it.
  - nonethewiser 4y ago
    That's true. They should never be asked to touch the cli on this scenario.
stcredzero 4y ago
> 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 Given the number of non-programmers who Really Need the functionality of git, who probably won't be able to hack dealing with it, doesn't this indicate that there's some huge vein of untapped value to be won by whomever cracks the problem? (Version control for business people?)
user3939382 4y ago
The Google Docs/Sheets version history strikes a pretty good balance of friendliness and power. The biggest weakness I've seen with it in the hands of non-technical users is that they don't know it's there.
jorgesborges 4y ago
In fact you lost non-technical people at Markdown.
- pxc 4y ago
  Non-technical people used to learn bits of HTML just to get sparkly backgrounds on their MySpace pages. Markdown is absolutely masterable by anyone.
  - jorgesborges 4y ago
    Definitely. My thought is rather that it’s an additional point of friction that makes selling a workflow like this more difficult.
  - RadiozRadioz 4y ago
    > Non-technical people used to learn bits of HTML just to get sparkly backgrounds on their MySpace pages. 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.
    - yamtaddle 4y ago
      There were tons of users in the 90s who didn't have a clue how to use a computer—I mean even at a very rudimentary level—and just followed memorized or written-down steps, getting lost almost immediately if anything went wrong. Luckily for them, software was way less likely to throw up "what's new" modals seemingly at random, interrupting whatever they were trying to do, back then :-/ (edit: or to "improve" [pointlessly re-arrange] their UI while the user was away from the computer, for that matter) If there are more of them now it's probably because computer use expanded 100 fold since then, at least, and the largely self-selected 90s users of the Web, especially, tended to have greater-than-average interest in learning computer crap, so a high proportion of new users were the can't-or-don't-want-to-learn sort. In the 90s a computer still might not be the centerpiece of an office worker or middle manager's desk, and most folks used computers very little at home, if they even had one (data I'm seeing indicates % of households in the US with a computer only hit 50% in 2000).
divbzero 4y ago
GitHub wikis or something similar can work well as an in-between option: edit in browser or git clone, whichever is easier in your context. https://github.blog/2011-01-17-git-powered-wikis-improved/ https://github.blog/2011-01-17-git-powered-wikis-improved/
deleted 4y ago
[deleted]

rcarr 4y ago

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 experience that there's a hell of a lot of merge conflicts going on with documentation anyway but I could see how it could happen if you had multiple non technical people actively working on a project. Another not great but possible solution could be for non technical people to work on something like a Google Doc when stuff is in highly active development and to then copy this to a markdown document later when its solidified. I do think that as a society we have to start looking at stuff like this as a new essential skill though. We wouldn't expect people to be working without basic literacy, numeracy and computer skills and I think we are going to have to start looking at upgrading our sense of what basic computer skills entails to include stuff like git and teaching it in schools from an early age.

jonwest 4y ago
GitHub does offer the ability to modify files within the web UI and open a PR from there.
remus 4y ago
I think even the idea of merging changes is a step too far for all but the most technical users. Most user's idea of what it should look like start and end at a word-like UI, so having to introduce the idea of merging different copies together and resolving conflicts is too far outside that view. In my opinion this is why Google docs has become popular because it solves that tricky problem of having to think about how your edits interact with someone else's.
- rcarr 4y ago
  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.
  - bpicolo 4y ago
    I'm technical and I still prefer WYSIWYG for writing documents. I want it to be easy for me to pull in rich content (images, info boxes, column formatting) It's ok to be technical and not enjoy markdown, heh.
  - evolve2k 4y ago
    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: > Most WYSIWYG editors are wrappers around HTML’s contenteditable and execCommand APIs, designed by Microsoft to support live editing of web pages in Internet Explorer 5.5, and eventually reverse-engineered and copied by other browsers. > Because these APIs were never fully specified or documented, and because WYSIWYG HTML editors are enormous in scope, each browser’s implementation has its own set of bugs and quirks, and JavaScript developers are left to resolve the inconsistencies. > Trix sidesteps these inconsistencies by treating contenteditable as an I/O device: when input makes its way to the editor, Trix converts that input into an editing operation on its internal document model, then re-renders that document back into the editor. This gives Trix complete control over what happens after every keystroke, and avoids the need to use execCommand at all. Unfortunately Trix does not render markdown so can’t be used in a markdown documentation workflow. Has anyone seen a decent implementation of WYSIWYG for markdown that has the necessary polish to be non-tech friendly?
    - rcarr 4y ago
      I believe Obsidian are using ProseMirror or CodeMirror, the logo is at the bottom of CodeMirror so I assume it is the latter. There was this forum post from one of the Obsidian team a few years back asking about it https://discuss.codemirror.net/t/implementing-wysiwyg-markdown-editor-in-codemirror/2403 https://discuss.codemirror.net/t/implementing-wysiwyg-markdo... https://codemirror.net https://codemirror.net https://prosemirror.net https://prosemirror.net

joegahona 4y ago

> Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people. How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?

vasco 4y ago
Most of the issues with Confluence I've seen are lack of organisation, out of date information mixed with up to date pages and really poor search / discoverability. The fact that people can just edit or create a page at any point is one of the better parts because it's easy for someone to fix something up during onboarding, during a drive-by consultation etc.
- bratbag 4y ago
  Even poor discoverability can be fixed with labels. But yes, the out of date info is a killer.
otikik 4y ago
Google Docs
WorldMaker 4y ago
There are Wiki-like interfaces for git+Markdown: GitHub's wikis, gitit, and more.

nonethewiser 4y ago

> 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 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.

carom 4y ago
Or just download Github Desktop onto their machine and show them how to use it.
- nonethewiser 4y ago
  That's true. They should never be asked to touch the cli on this scenario.

stcredzero 4y ago

> 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 Given the number of non-programmers who Really Need the functionality of git, who probably won't be able to hack dealing with it, doesn't this indicate that there's some huge vein of untapped value to be won by whomever cracks the problem? (Version control for business people?)

user3939382 4y ago

The Google Docs/Sheets version history strikes a pretty good balance of friendliness and power. The biggest weakness I've seen with it in the hands of non-technical users is that they don't know it's there.

jorgesborges 4y ago

In fact you lost non-technical people at Markdown.

pxc 4y ago
Non-technical people used to learn bits of HTML just to get sparkly backgrounds on their MySpace pages. Markdown is absolutely masterable by anyone.
- jorgesborges 4y ago
  Definitely. My thought is rather that it’s an additional point of friction that makes selling a workflow like this more difficult.
- RadiozRadioz 4y ago
  > Non-technical people used to learn bits of HTML just to get sparkly backgrounds on their MySpace pages. 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.
  - yamtaddle 4y ago
    There were tons of users in the 90s who didn't have a clue how to use a computer—I mean even at a very rudimentary level—and just followed memorized or written-down steps, getting lost almost immediately if anything went wrong. Luckily for them, software was way less likely to throw up "what's new" modals seemingly at random, interrupting whatever they were trying to do, back then :-/ (edit: or to "improve" [pointlessly re-arrange] their UI while the user was away from the computer, for that matter) If there are more of them now it's probably because computer use expanded 100 fold since then, at least, and the largely self-selected 90s users of the Web, especially, tended to have greater-than-average interest in learning computer crap, so a high proportion of new users were the can't-or-don't-want-to-learn sort. In the 90s a computer still might not be the centerpiece of an office worker or middle manager's desk, and most folks used computers very little at home, if they even had one (data I'm seeing indicates % of households in the US with a computer only hit 50% in 2000).

divbzero 4y ago

GitHub wikis or something similar can work well as an in-between option: edit in browser or git clone, whichever is easier in your context. https://github.blog/2011-01-17-git-powered-wikis-improved/ https://github.blog/2011-01-17-git-powered-wikis-improved/

deleted 4y ago

[deleted]