README.md

GitHub For Non-Code Writers

updated 21 April 2022

GitHub is not only for software developers and if you are a writer, just like a blogger, even non-tech, you can utilize GitHub. It really fits your need as a writer.

Many will be discouraged to even start because they think that GitHub is only for software developers but it's not!

Think of this situation: a source code is purely text, unless it's graphical coding. But most of real-world software development is text-based, graphical coding is just an option for beginners particularly in the academe. Now, there are several documents that are actually pure text too. Just to name a few, a poem, a legal document, a novel: they are pure text in their natural form.

Now, you'll say that other documents should not be plain text but rather a rich-text document, but I'm sure that you know that as a writer, it's highly encouraged to write in plain text so that it can be rendered to different formats when published, just like a PDF, a web page or an ebook.

And then we have the full option to simply use, say, online word processors. But you want to avoid specific platforms, because once you have utilized one, you are confined to that. No matter what, once you open a certain document using a different platform or word processor, there will be unexpected changes. But a plaintext document can be opened on any other machine that you want to use.

But what if you insist, say, your company will only use Google Docs, but still, as was mentioned, once your content is published, it's really unpredictable. So, it's better to write in plaintext format. GitHub is an excellent tool for plaintext documents. You have all the luxury of revision control, a centralized space for collaboration, a service to simply turn your content as a web page through GitHub Pages, plus you have the Markdown that renders your plaintext document as an elegant one but preserving the plaintext document. Plus, you can easily get a rendered HTML if that will be required. And it's really fast compared to WordPress and others.

Now, GitHub is using Markdown for plaintext documents, so that it can be rendered in an elegant way (but again, you can still create a pure text document by indicating it with filename extension .txt), that's the reason why the default README filename extension is .md, indicating it is a Markdown file. Don't be afraid to learn and use Markdown. It's simply a collection of very simple annotations for your plaintext format but again you still preserve the original form. When we say annotations, you are telling that there are certain styles that should be applied to some words, phrases or even the exact format of your document, for example, a certain word will be bold when printed. Another example, to organize a document, you'll be using headings. You simply add an # before the title so that it will be rendered as the title or Heading Level 1. Use two ## for second level headings. (In short, how your plaintext document will be rendered exactly the way you want it.) As you can see, you still preserve the plaintext format.

For the complete details about Markdown, (don't worry you can learn this instantly):

https://guides.github.com/features/mastering-markdown/

And other sites are mentioning that you need to use Git. No, you don't need that, not even GitHub Desktop, if your focus is writing in plaintext format. The GitHub Web UI is enough for your workflow.

Steps

So, having said all the encouraging things, let us start!

Step 1

Create a GitHub account (you just need an email then follow all instructions):

https://github.com/join

Step 2

Create a new repository (think of it just like a regular folder) but since your focus is writing content, it will serve as one post, I highly encourage for every content you write is another separate repo (but it is just a matter of personal preference):

You'll be seeing the above image if you are at your dashboard.

To visit your profile, go to upper right corner of your screen then you'll see your avatar, click that

or directly go to Your repositories, so that you can create your new repo.

Step 3

Initialize your repo:

• think of an elegant name of your repo, this will also appear as part of the URL
• make it private first so that it is still your draft
• fill in the description by powerful words describing your entire work, this will also be used by GitHub Pages when you turn your repo into a web page and will also appear as short description when you share your repo on social networking sites

• initialize a license or don't include, GitHub rule is that when there is no license, it's copyright
• don't include .gitignore, it's needed when you use Git, but you don't need this for simply creating content
• the README file is very important, it's the default display of your repo, so it serves as your page, this is also true when you enabled GitHub Pages

Step 4

And when you click the Create repository, you're done with your setup, you will be seeing your repo and you can start writing when you click the pencil button.

Then type anything you want (just to test), click Preview changes

then at the bottom, once you see the preview of your changes, click Commit changes

and you just have your first commit! That will appear on your GitHub profile. Remember, you are editing the file in pure text form but you are using Markdown tags.

Now, for my details of how I'm doing my workflow, check this out:

https://github.com/xdvrx1/my-personal-content-dev-workflow

A Little Bit Of Housekeeping (not required)

Now, you have the option to remove unnecessary things although this one is not required. Click the gear button as demonstrated below:

uncheck Releases, Packages & Environments and add labels so that it can be discovered by others when they are looking for topics

then go to the Settings of your repo (once you made the repo public)

and you can uncheck Wikis, Projects and include Discussions tab.

There you can also make your repo as a template so that it serves as your template. Also, make sure you include a social preview so that it's really presentable when you share your repo to other social networking sites.

About GitHub Pages

Right on GitHub, if you want to turn your repo as a web page for digital distribution and online presence, make sure first that it is public (for free accounts, it is not allowed to enable GitHub Pages of private repos), if you read the link I gave you for my personal content development workflow, I mentioned that.

Now, once the repo is already public (again, for free accounts), go to Settings again, and you should look for the Pages tab at the left pane.

Then,

you must select main as the source, so that it is automatic, your README file will serve as the default page, without changing anything, then click Save first, then select a theme.

Here is the complete tutorial for GitHub Pages:

https://github.com/xdvrx1/github-pages-tutorial

Formatted Content Through Markdown

The formatted content through Markdown can be pasted on Google Docs and the format will still be correct, in case you will be needing an equivalent Google Docs version.

Creating PDF

There are two ways to create a PDF version of your content without installing anything, first through GitHub Pages, once you have the web page, right click it then select Print but instead of printing it, save it as PDF.

The other one is through Google Docs, once you pasted the rendered content, click File on Google Docs, then select Download as PDF.