In this episode of the Cherryleaf Podcast, we look at GitHub and how technical communicators are using GitHub for creating documentation.
Transcript
This is the Cherryleaf podcast.
Well, hello again. I thought in this episode it would be good to look at GitHub and how technical writers, technical communicators, technical authors depending on what you call them are using GitHub for creating documentation.
We’ve had some projects starting off where we’ve needed to brief the writing team on how to use GitHub and for some GitHub was a new tool or environment for them to use, and some of the concepts and approaches and philosophies of GitHub were unfamiliar. And that may be the case for others as well, so I thought it would be good to have a look at how you can use GitHub for documentation.
And also look at some other features, if you have used GitHub, that perhaps you’re not aware of. What we might do is supplement this podcast with a video to show some of the features in GitHub which we would put onto YouTube.
So have a look in the show notes for this episode because there may well be a link to a video illustrating some of the things that will cover. So what is GitHub?
GitHub is a repository. It’s designed principally for developers as a place where they can store on the Internet in the cloud, as it were their code. The code that they’re developing or that teams can use.
There are others out there like GitLab and Bitbucket, but in this case we’re going to focus on GitHub. It’s the most popular of all these types.
It’s a repository for code. It can also be used for being a repository for documentation.
And if you’re working in an environment that’s sometimes called docs like code or docs as code.
Where you want the code to be stored and to be reviewed and to be published in a similar way that the code for an application is stored, reviewed and published, then having it in repository on GitHub.
Is it good?
GitHub comes with different versions. There’s a free version that you can use, and there are also paid versions with the free version, your repositories are publicly viewable publicly, available with the paid versions.
You can hide them and only certain users can see them and you’ll find GitHub at www.github.com.
Now there also is a desktop application and we’ll talk about that later, which you can download and use for managing your files and uploading and downloading from the repositories.
So repository is just like a folder of files, like a project really and we can look at an example of that by going to the Microsoft documentation, because Microsoft now stores its help documentation in repositories. On GitHub we can go to www.docs.microsoft.com and we’ll find a website that has Microsoft technical documentation, and on that page there’s a product directory in the product directory.
One of the links is to Microsoft Teams, so we can click on that and we’ll get to the Microsoft Teams admin documentation. And if I click on the link for deploy,I get to the help for deploying Microsoft Teams.
And you’ll get into a Microsoft Teams deployment overview page.
And in the top right hand corner on that page is an edit button.
And what will happen if I click on that edit button is it will take me to GitHub and it will take me to the repository for Microsoft Teams.
And there’s a readme file that gives a description of the deployment, and if I click on the link for Teams, I get to the repository for Teams and there’s a whole bunch of files and folders for the documentation.
So in this repository for Teams is the files and the Cascading Style sheets and JavaScript relating to creating the pages for the Teams help content.
Now if you clicked on any of those files, or if you looked at those files, you’d see that they’ve got the extension .md being short for markdown.
So what’s happening is, is that to make that page appear for the help for Teams, there’s also a conversion process that’s going on that’s converting these static markdown files, combining them with the cascading style sheets, using the JavaScript to present the help pages by itself.
This is just a store for the content. There is a publishing process or publishing tools that are being used to publish this content to be web pages that people can use.
So we have a repository of the documentation, and that’s basically how GitHub is also used by developers for the repositories of the code that they want.
So it may be that somebody has developed an open source application and they are willing to make that code available for other people to use, and so one of the things that we can do and one of the concepts that we can familiarise ourselves with is we can do what’s called a fork of the repository.
So if we think about that first within a code environment this: imagine somebody has developed an application. It might be that it provides the share price or the stock price for a company and it will update automatically with particular code so that it would appear on a web page or appear in an application. And rather than write to that code again, an organisation might want to use that code in their own application so they don’t have to write it.
So what you can do is you can make a copy of the code and the terminology for that is called fork, and then you could incorporate that into your application.
So then there’s two versions of the code. There’s the code that the developers developed that’s doing its own thing, and then there’s your version where you’re using it in your application.
If you make changes to your forked version, then that’s not changing the other version that the original developers created. So when you hit fork, what you can do is make a copy of a repository in your own saved folders within GitHub under your name. There’s a copy of the repository.
Now, once they’re completely separate in two different areas, what you can do is, if there are any bugs that appeared and the original source developer made updates to their repository and that bit of code, you can get it to then update your forked copy of that particular repository.
So how could we use that within a documentation environment? How can we use this idea of forking a repository well?
If we go back to our Microsoft example.
Where we’ve got this documentation for Microsoft Teams, we might come into a situation where we would want to create our own customised version of that documentation. That in addition to the information that Microsoft have written about how to deploy teams within an organisation, we might want to modify it, by adding extra information about how we would deploy it within our own organisation. So we can create customised, personalised version of the documentation.
Now, this isn’t as sophisticated as you can do in tools like DITA, where you’ve got things like conrefs for having personalised versions of content, but it’s pretty close and would work fine for a lot of organisations.
So what you can do is you can in the top right corner and you can hit the fork button and it will ask you where you want to fork the repository to.
So we have a GitHub account called cherryleaf. We clicked on that. It would then process that request and fork that documentation for Microsoft Teams.
Into cherryleaf and create a repository on GitHub which is a copy of that particular repository.
So that’s one way in which GitHub can be used for documentation. So we’re making copies and personalising it. But the more common way in which GitHub is used for documentation, is more where we’re creating branches of a repository.
Imagine we’ve got a job at Microsoft or we’re working for Microsoft and the Microsoft Teams documentation has got some elements where it’s out of date. It needs to be updated.
We can take that content that’s in the repository for Microsoft and we can make changes and we can submit those to be considered to be published.
But for safety’s sake, what we might want to do is create a working folder where we can make the changes that we want away from the live site. And when we are ready, submit those changes to be reviewed to be considered and to be published to the live site.
So what we can do is we can create what’s called a branch. And at the top on the left hand side of the repository there’s a button that says live, and if we click on that what we can do is we can create a new branch of that live that main repository.
And what will happen there is we will make a copy of that repository with the view that when we make changes, we can submit them and actually change them to the core main repository to Microsoft’s own documentation.
Typically we’ll make a branch for a client of their repository and we’ll call it cherryleaf so that they’re aware that that’s the folder where we’re making the updates and edits and changes, which we’re then going to submit for them to approve and to get published to their live site now.
So far, what we’ve talked about is GitHub and making repositories.
On the GitHub com website, often what people want to do is they want to work locally. They don’t necessarily want to work in the browser.
And so one of the applications that GitHub provides is something called the GitHub desktop, and you can download that from the GitHub website.
And if you install that programme and configure it so that it knows that it’s your account, what it will do is it will make a copy of those repositories you’ve accessed.
And it will make copies of those locally on your computer, so you can use your preferred authoring tool to make changes to the documentation locally. And what you can do is when you save that particular file, the GitHub desktop will recognise that that file has changed.
And what you can do is then do what’s called a commit. And what a commit means is that it will then those changed files that are on your computer, copy those up to the cloud version: The GitHub.com version of the repository.
Now, it may be that there’s other work going on on the documentation. It may be that the client may be that Microsoft, if we’re talking about Microsoft again, is making changes to the documentation. So there’s this risk that what you’re doing gets out of sync with changes that other people are doing.
So one of the things that you can do with GitHub, and again with the GitHub desktop, is get those changes that are happening and incorporate those into your branch into your copy of the documentation. So you’re kept up to date with what changes are happening elsewhere on this main live repository.
So the buzzword for doing that is either refresh or pulling the origin. And that means you’re pulling down from that main repository the latest files that are happening. So typically what you do, when you start to use GitHub in the morning to make changes to the documentation, is you would pull down any changes that have happened overnight. So that you’re up to date with what’s going on.
So what happens is you’ll make changes, and they’re being made to your branch of the documentation. And you’ll get to a point where you want to submit those changes that you’ve made for review, so they can be incorporated into the live main branch.
To do that, what you can do is what’s called a PR or a pull request, to request that the changes that you have made will be incorporated into the main branch.
So, when you do that using the GitHub desktop, it will then submit them, take you to the github.com site. And you can write a brief description of what’s changed, why you think these should be accepted. So we have then done a pull request. And then there will be somebody who is the owner of that repository, they will look at the changes and they will either accept the changes, not accept them, or they will request changes to be made before they accept them.
Now one of the features within GitHub is that it will show you where content has changed, so it will show you the line that was in the original content and the proposed change. One in red if remember correctly and one in green. And you can see what the difference is between them.
So in this way, the reviewing of the documentation can be done in the same way that the code is being reviewed. Reviewing it in GitHub.
Now, it used to be the commands for pulling the information down, committing the changes that you’ve made, making pull requests was rather convoluted and complex, and you had to use commands. Instead, to do that you can use the GitHub desktop. Then it’sessentially a case of pushing buttons within the user interface, so it’s a lot easier to.
So with branches, you have the main live branch. And then what you can do is you can create just sub-branch where you can make the changes that you want and then submit them.
Make a request for those to be incorporated into the main branch.
Another common scenario is where you are in an environment where there are different versions of software. So it’s version one. Then there’s version two that’s coming out soon. And so, as with the code, you can create a branch and the developers can work on version two in that branch. And when it’s ready to go live, it can then go live.
The same thing can happen with the documentation. You can have branches of the documentation, the different versions, version 1, version 2, version 3.
So conceptually, there are some things that are different that you need to be aware of. The idea that they can be the content in the cloud and the content locally.
And that you have to make sure if you make any changes locally that you then commit them to go back to the cloud, that there are these different repositories, and that there can be forks of repositories.
And then there could be branches where you want to make changes to that source. That main documentation make those changes and have those incorporated into the live documentation. And the process by which an organisation works, and how they go through the review process and approval process can vary.
So it’s good to know how they want to work.
Do they want to work with branches which branch they want you to work on? How often do they want to review and approve the content. Do they want you to make multiple pull requests requests for the content to be added to the live site, or have just one main pull request and keep adding content to that for them to review?
Now, some of the other features within GitHub are that it can do things like what’s called automatic linting or automatic checks. So it can go through and if there are hyperlinks within the documentation, it can cheque that those hyperlinks are valid. So that can save time.
And there’s also a new service that GitHub is introducing called GitHub copilot. Now this is primarily designed for developers by using artificial intelligence, getting suggestions for whole lines or entire functions of code whilst the developer is writing code.
And it can also convert comments into code, so you can write a comment describing the logic you want, and GitHub can suggest or assemble the code that matches with that particular comment.
Chris Ward, who is a Technical Author, blogger and also a journalist, has been investigating whether copilot could also be used for generating some documentation.
And he’s been doing some experiments on whether it could be used for technical documentation and also creative writing, and he’s published two videos on YouTube on his experience in doing that. And in the show notes, we’ve included links to those two videos.
Another feature that is available with GitHub that might interest you is GitHub pages. GitHub pages is a static site hosting service. And that can take markdown, HTML, cascading style sheets and JavaScript from a repository on GitHub and process them through a build process and publish a website. So this means that you can host a static website on GitHub pages. And as you’re enabled to have one site per GitHub account free of charge, that you can have a website for free. So the way that it works is you create a repository. You clone the repository, you create what’s called an index file, and then you commit and publish. Having hit the publish button, you’ve then got web pages on your GitHub website. And you can configure it so a custom domain shows up. So if your name is Fred bloggs.com it displays this GitHub homepage.
Where this is useful is if you want to have your CV and you’re linking to lots of repositories on your CV on the Internet. It’s good for that. Or if you wanted something like a wiki. Avery simple small website.
There are some downsides.
The pull requests can take a while to get published. Although that could be solved with more people involved with the approval process and permissioning or automating approvals. I’ve heard the search engine optimization is very poor, so your site is not necessarily likely to be found by the search engines and also there’s generally not an easy way to search the page contents.
But if you want a free simple website available on the web on the Internet, then it’s a handy so.
So that’s a 20 minute summary of GitHub and how technical communicators can use it for different needs.
Before we finish up, just some news on new course bundles that we’ve introduced, we’ve introduced a bundle on technical writing with our API course. Our technical writing course with screenshots course, another bundle which is the Technical Writing Foundation with onboarding course. UX and technical writing, with copywriting and technical writing, with writing UI text. So these are bundles with two courses: our foundation course and then an optional one.
If you’d like to find out more information about these new bundles, then if you go to cherryleaf.teachable.com, then right at the bottom of the page listing all of the courses, you’ll find details on these bundles, where you can get the two courses combined at a discounted price.
You’ll find information on Cherryleaf’s other services at cherryleaf.com, and you can always contact us info@cherryleaf.com. Thank you again for listening. Look forward to speaking on the next episode of The Cherryleaf Podcast.
Leave a Reply