Outline - pglevy/github-for-creators GitHub Wiki

Why GitHub?

  • Free: With public repos, you get full access to all the features described in this ebook with a free account (this ebook assumes public repos, some notes about private repos)
  • Robust: GitHub has been around a long time, and there's a huge support network. Also the underlying Git technology is inherently decentralized, with content stored in the cloud and locally.
  • Control: GitHub is essentially just a place to put stuff. Everything you do with it remains your stuff and you can pick up and leave with all of it at any time.
  • Open: The ethos of GitHub is open source. While it's perfectly fine to make a license for your content that suits your needs, I believe there is value in building in public. This is baked into the way GitHub works.
  • Collaborative: Because of it's origins in building software, GitHub is a natural tool for collaboration, allowing multiple to work on the same at the same time without stepping on each other's toes.

The different between git and GitHub

  • Git is the underlying version control technology. GitHub is a cloud-based service that makes it easy to use this technology for a variety of purposes and super charges its creator capabilities by adding a ton of cool features we'll cover in this ebook.

Overview

  • Managing projects
  • Sharing knowledge
  • Creating content

Glossary

(see existing in Methods repo)

  • use of "creations" (projects vs. products)

Cool things about GitHub

  • Everything has a URL
  • All the features can be used together or independently, whether you're using GitHub as a content creation tool or not (separate products).
  • Gists
  • Built-in text editor (VS Code)

Quirks

  • Although Markdown is supported nearly everywhere you can enter text, the visual editing controls vary. (For example, links)

Learning to speak Markdown, the language of GitHub

  • Traditional content editors: mixing content and presentation
  • Learning from the web: separating content and presentation
  • Bi-lingual: speaking both machine and human
  • Write once, use almost anywhere
  • GitHub-flavored markdown (GFM)
  • The basics and other references and tools

Managing projects

  • Project boards
    • Similar to Trello, Asana, and other project management tools
    • Completely customizable, including automation
    • Each card has a URL
    • Flexible: multiple projects per repo; repo projects and account projects (for managing more complex projects across multiple repos)
    • Can use simple cards/notes or more full-featured issues
  • Issues
    • Individual, atomic item of work to track
    • Add desciptions (remember markdown!)
    • Assign one or more people
    • Track conversations and decision in comments
    • Even descriptions have version control, so you can always see what change someone made and when
    • Tracking progress: either open or closed; for more options, use Project boards
    • Build in public bonus: issues can be a way to gather input from your audience — people can create issues for reporting problems or making suggestions. You can even use automation tools like Zapier or IFTTT to enable people without GitHub accounts to submit Issues using simple forms.
  • Milestones
    • A way to group issues and show progress
    • Gives a more bird's eye view than projects, which can get very granular
    • Attach descriptions and due dates (remember markdown!)
    • Use as a roadmap for your creation
  • Releases
    • Good way to signify a meaningful collections of updates
    • Flexible: no rules for naming conventions or intervals; whatever works for your creation
    • Tip: start with a draft to clarify what you intend to do
    • Use markdown for well-crafted messages about a particular landmark in the journey of your creation
    • Surface the important history of your creation

Sharing knowledge

  • An important aspect of building a community around your creations is sharing knowledge
    • Do this in many ways: social media, blogs, videos, etc.
  • Wikis: the ultimate tool for networking knowledge
    • Wikipedia, incredibly successful, built on WikiMedia technology
    • GitHub not quite as robust, but covers the basics
    • Makes it super easy to build community-based web
    • Can all be done in the browser, multiple editors, version history
    • Idea: Tool that takes GH Wiki content and presents as a standalone website?
    • Examples:
    • You get this built in:
      • Sidebar navigation
      • Search
      • Version history for each page
      • Custom sidebar and footer
      • Public URL for each page
    • Gotchas
      • Dashes (other characters in titles?)
  • Discussions
    • Get your community talking to each other
    • Q&A format with ability to mark questions as answered
    • Upvoting to check the pulse of your audience on topics and suggestions
    • Custom categories
    • GitHub Community Guidelines
    • Tip: Converting discussions to issues
  • Templates
    • Roots of open source, adding to or remixing other people's content
    • Difference between other people contributing to your creation or using your creation as a starting point for their own creations
    • Provides one-click setup for using your repo as a starting point
    • Using other repos as starting points

  • Gists

Creating content

  • Repos
  • Basic content types: text and everything else
  • Just tracking stuff (remember markdown!)
  • Plain vanilla GH Pages
  • Jekyll: the built-in static site generator
  • Setting up a blog
    • built-in themes
    • other free and paid themes
  • More complex sites, using frameworks (Bootstrap or USWDS)
  • Non-web or other standalone content
    • BMC-ebook-template
    • Illustrations, svgs, and other artwork
  • Using other repos as starting points
  • Keep in mind Project management and knowledge sharing tools
    • track your progress and assign tasks to collaborators
    • capture instructions or other documentation in a wiki as you create
  • Custom domain

Capability cross-reference

Getting feedback from your audience

  • Issues: report problems and make suggestions
  • Discussions: foster group input with threads and upvotes

Publishing to the web

  • Wikis:

Appendix

  • Private repos
  • Large files

(Potential) Resources