GitHub and Doc Reviews Workflow #22319
-
I’m a techwriter who has hopped on the docs-as-code bandwagon, inspired by Tom Johnson’s idratherbewriting blog. I’m working on a client site, where I’m creating a Help sub-domain for their user and config documentation. Up until very recently I had no experience of Git, GitHub, Jekyll and the rest, so it’s been a crash course. It’s coming along OK, but I have some basic questions, of which this is one. I’m suggesting to this client company that we use the Edit Me functionality on GitHub for their people to do updates and reviews on the content I’m publishing for them. It’s a pretty tech-focused company so most of the crew are reasonably tech-literate. So I have some questions about this proposal. Will each of them have to have a GitHub ID to perform reviews using this method? And unless I designate some or all of them as Collabators, then if they review any of the pages I’m publishing on their behalf, any review will automatically fork the whole repo onto their GitHub profile? (I think so, because I corrected a typo on Tom Johnson’s site and as a consequence I have a copy of his repository under my profile. Can I delete that without issue?) I guess this is leading me to question the overall utility of using GitHub for documentation reviews. It makes a lot of sense for the developers and engineers who are used to Git. But I don’t know if that is the case for sales, marketing and delivery personnel who otherwise would never have any exposure to Git, because it means in addition to making sure they get the basics of markdown and so on, they also have to have some basic grasp of Git. It will also mean that as the site develops, there will be multiple accounts with forked versions sitting under them. I am aware of some user-friendly tools that are around, like prose.io and some easy Markdown editors, but I am concerned that the GitHub review cycle might be overly complicated for many of my users. |
Beta Was this translation helpful? Give feedback.
Replies: 3 comments
-
I do agree on the entire GitHub thing being a bit too hard for regular users. And yes, each user will need their own GitHub account + a fork of the repository to make changes. Have you considered alternative CMSs like https://prismic.io/ or https://directus.io/? |
Beta Was this translation helpful? Give feedback.
-
I can understand the concern about the Git flow being a bit more heavy-handed than what most non-tech-focused people are used to. Let me try to address your direct questions first though: Yes, each of them would have to have a GitHub ID to participate in a meaningful and understandable way and also to comply with our Terms of Service. On the other hand, each of their accounts could be on the free tier if I’m understanding how you’re describing the work will be organized correctly. If you designate them as external collaborators on your repository, then no, they would not have to fork your repo in order to make changes or submit reviews, even if your repository is private. In correcting a typo on Tom Johnson’s site, his repo was forked to your account specifically because you were not designated as an external collaborator, just an unrelated GitHub user on a public repository. To return to your question about the utility of the workflow for non-tech-focused roles such as sales and marketing. GitHub’s own sales, marketing, legal, facilities, and other traditionally less tech-focused roles use the GitHub flow for their own documentation and communication to a greater or lesser extent. We won’t deny there is a learning curve. On the other hand, we feel that the benefits to collaboration and especially transparency and maintaining a history of comments and decisions that can be referred back to, in perpetuity, is a huge benefit that outweighs the cost of the learning curve for us. I hope that helps! |
Beta Was this translation helpful? Give feedback.
-
thanks Lee - for some reason, I hadn’t noticed your reply until now. In the time since, some of my concerns about using GitHub have abated - the technical users at the client site certainly feel completely at home with it, and I’m hoping that they can help orient the front-office folks who want to contribute. Management has declared that it’s happy with GitHub being the doc system, so that is the main thing. |
Beta Was this translation helpful? Give feedback.
I can understand the concern about the Git flow being a bit more heavy-handed than what most non-tech-focused people are used to. Let me try to address your direct questions first though:
Yes, each of them would have to have a GitHub ID to participate in a meaningful and understandable way and also to comply with our Terms of Service. On the other hand, each of their accounts could be on the free tier if I’m understanding how you’re describing the work will be organized correctly.
If you designate them as external collaborators on your repository, then no, they would not have to fork your repo in order to make changes or submit reviews, even if your repository is private. In correcting a …