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.