
How and why we teach non-engineers to use GitHub at Thread - danpalmer
https://thread.engineering/teaching-non-engineers-how-to-contribute-code-2e85411ab464
======
kaikai
Mapbox does this too, even as we've grown to 300 people. When I first joined
every single employee had to put themselves on the team page, going through
the whole commit, test, and push process with the help of someone who knew
how. We have repos for everything, and use issues for things most people would
write an email about.

Not only is our website easier for non-technical folks to update, but that
means we have built-in transparency for much of the business. There are
private repos for things that don't need to be aired company-wide, but public
is the default.

~~~
bonesss
> We have repos for everything, and use issues for things most people would
> write an email about.

I really like this.

When it comes to productivity in the enterprise I'm quite fascinated by the
intersections of communication immediacy versus persistence. We like things
that are immediate when we speak, but like things that are persistent when
we're digging around years later.

A searchable per-theme repo with searchable issues and dialog sounds like a
dream. I dunno if github has this built-in, but their integration API is very
nice so having direct email integration and notifications or even local
notification clients should be highly solvable.

~~~
Mouse47
Of course, you have to work with people where reading/writing isn't an issue.
I've worked in several environments where it seemed nobody could read, and
nobody could fathom why what they wrote wasn't 100% clear.

------
learc83
Instead of teaching employees to use git, why don't you put all of your data
files on S3 and enable versioning?

If the non-engineers are just using git to upload and version json files full
of data without modifying the code that reads them, uploading to s3 seems like
a much safer and easier way to accomplish the same goal (without building CRUD
interfaces to handle it).

~~~
codemac
It is an incredible failure of modern version control systems that distributed
branching means that they're impossible for novices to use.

However, if you see github.com as a proprietary UI for git, it looks almost
exactly like putting your files on S3 with some CRUD UI around it.

~~~
busterarm
> It is an incredible failure of modern version control systems that
> distributed branching means that they're impossible for novices to use.

No it isn't. This is entirely a sales problem.

You may not have noticed, but engineers typically can't use distributed
branching either. The volume of tutorial and "i'm in trouble, plz hlp"
material out there for Git (and really every other VCS) is substantial.
Everyone has a story about how a certain workflow got them into trouble on a
project.

The thing is, collectively we see a huge value in it, so we make the learning
investment to use it. It's only after we learn it (and the pitfalls to avoid)
that it's easy.

Novices don't use it because they haven't had the value proposition made to
them yet. If you can reframe the argument for why, you'll get them using it.

~~~
crdoconnor
It isn't a sales problem either. It's a tooling problem.

Git really ought to be treated as a low level tool that is called by a higher
level tool that assembles content management workflows designed by developers
that can be used by developers and non-developers alike.

Non-developers ought to be able to make 'commits' with git and pull requests
without even realizing that git is the underlying tool.

Developers should just script their most common workflows and then use them
99% of the time.

Unfortunately the tooling that sits atop git is largely all shit and people
have gotten it into their heads that one needs to have a deep understanding of
git's quirks to be considered a 'serious' developer.

~~~
bonesss
I agree with your premise, but don't understand your conclusion...

> Non-developers ought to be able to make 'commits' with git and pull requests
> without even realizing that git is the underlying tool.

Absolutely. By why 'ought'? What's stopping you?

Git has an API, lots of tools use it. There are commercial products that wrap
git for designers and such. Many of my systems are GIT and Github enabled
(Octokit), and the users are none the wiser.

> Developers should just script their most common workflows and then use them
> 99% of the time.

I am almost positive this already exists in many various forms online (on
github in particular), for personal needs. I know a significant number of
projects script checkins, builds, etc.

It breaks down, IMO, because of environmental constraints. You're trying to
maintain alias sets across machines, on colleagues machines, or handle tricky
merge issues per-project. At the end of the day the APIs breadth is required
to handle corner cases, and familiarity with the breadth makes a lot of noise
'straightforward'.

~~~
crdoconnor
>Absolutely. By why 'ought'? What's stopping you?

I don't know of any decent tools. Something that would give an end user a nice
UI to let them edit a markdown or JSON/YAML file and issue a pull request
following a team defined workflow, for example? Or a WYSIWYG markdown editor
that can issue pull requests following a team defined workflow at the click of
a button?

>Git has an API

I noticed.

>I am almost positive this already exists in many various forms online

Most teams I've worked with don't have anything. One of the first things I do
when I join a team is figure out their workflows (typically baked into
people's heads) and get them down in a script.

>It breaks down, IMO, because of environmental constraints. You're trying to
maintain alias sets across machines

A) git aliases are a poor substitute for a decent workflow program.

B) A lot of workflows integrate a lot of different things - e.g. by
convention, branch names on new tickets often contain the JIRA ticket number
followed by a slugified name. That means to properly script a workflow you
need to make an API call to get a ticket number and slugify the name and use
it to create the new branch.

------
tootie
Square peg in a round hole. It sounds "non-engineers" means content managers
and they just invented a really crummy CMS. Surely they could at least use
Jekyll or something and let the content managers use markdown. They're
shifting the cost of dev time to content management resources when they could
just spend some cash on a commercial CMS like Contentful or Prismic that is
easy to configure and far safer and more scalable.

~~~
danpalmer
We actually have various CMSs for content like blog posts and human readable
text.

We use the solution in the article for things like the current delivery
estimate, which changes twice a year and is a Python timedelta object
(example, but more complex than that) or adding new tags to our support ticket
system (not user facing). For those, we don’t want or need to spend the
overhead of making an editing interface.

As for integrating another CMS, the whole point is that it’s just Python files
in the repo, zero effort for developers, very little effort for everyone else,
when editing is infrequent.

~~~
WorldMaker
I find it interesting that you mention you are using Django, since my feeling
has always been that easy/dumb/quick CMS CRUD interfaces has long been its
bread-and-butter, especially the Django Admin.

That said, I don't question the benefits of version controlling data, and the
usefulness of GitHub's web interface for quick and dirty commit work.

I am surprised that a quick search doesn't seem to turn up someone already
trying to build a NetlifyCMS-like tool for inside the Django Admin. That seems
like a natural fit for Django's CRUD philosophies.

~~~
danpalmer
We use a Django admin based CMS for part of our product, but most CMS
solutions are about things like blog posts or knowledge bases, not for complex
data models and changing configuration of an application (like our current
shipping estimate). Building editing interfaces in Django is relatively
straightforward, but by not doing it we can save hours, maybe a day, and
that’s worth it if we’d only use the editing interface for 5 minutes a month,
or are testing a new thing that we might throw away in a week.

------
maxxxxx
Aren't they using GitHub for what traditionally would have been done with a
CMS?

~~~
danpalmer
Yes, but the point is that now we don’t have to build a full CMS. Off the
shelf ones won’t typically work for the sort of content being edited (i.e.
it’s not blog posts etc).

~~~
busterarm
But you do need an Engineer to hit the merge button for you when a build is
green.

This is okay now, but could become a major pain when your company grows and
Nancy in Accounting who is an aspiring writer starts making _hundreds_ of copy
changes with pull requests every week. You're going to really wonder where all
your engineering time went when suddenly you have a dozen Nancy in
Accountings...or a hundred.

~~~
nkrisc
Then somebody sits down with Nancy and reminds her what her job is. If she
can't handle it still then you revoke her access or fire her for abusing
business tools.

~~~
busterarm
But you gave everyone commit access...and she is doing her job.

~~~
sgnl
In your example, her job is an Accountant. She can aspire to be a writer but
not on company time.

~~~
busterarm
But she gets her job done and probably very well. The point is that you gave
_everyone in the company_ the ability to contribute to the product.

If you do that, you are communicating to your employees that everyone is
welcome to make contributions to the product. If not, why the f __* would you
do it?

~~~
nkrisc
Because you expect your employees to behave like adults? I assume you don't
just give everyone access without and set them free without any training or
guidance. If someone can't handle a responsibility you take away the
responsibility and/or replace them.

I have access to pretty much every Confluence page at work, including ones
other people set up for executives to look at, but I don't go around making
changes and editing those pages just because I have access.

People aren't robots. You can hold them accountable for their actions and they
can make their own (good or bad) choices.

------
crdoconnor
Since you're using python and you're trying to store configuration style data
in something that you might want a non-programmer to maintain, might I suggest
storing the data as YAML and parsing with my library?

[https://github.com/crdoconnor/strictyaml](https://github.com/crdoconnor/strictyaml)

I wrote it partly to make it easier for non-programmers to maintain structured
data - which seems to be your use case. YAML is cleaner and easier to maintain
than python dicts/lists/etc, and with a strictly validated schema you can
trigger failures caused by accidental insertion of invalid data at an earlier
stage.

~~~
danpalmer
Thanks, I'll consider it for the future!

Python has worked fairly well for us so far though, we have tests that would
detect invalid syntax, and importing a Python file is easier than parsing and
doing the error handling on YAML/JSON.

~~~
crdoconnor
Shouldn't be much more than a 3-4 lines of code to import from YAML with this
library, especially if you have a simple schema:

e.g.

    
    
        import strictyaml as sy
    
        MY_TRANSLATIONS_DICT = sy.load(
            Path("translations.yml").text(),
            sy.MapPattern(sy.Str(), sy.Map({"French": sy.Str(), "German": sy.Str()})),
        ).data
    
        translations.yml:
    
        Hello:
          French: Bonjour
          German: Guten Tag
        Goodbye:
          French: Au revoir
          German: Auf wiedersehen
        
    

It would negate the need for most of those tests checking for invalid data,
too (the above would raise an exception instantly if there is a YAML syntax
error or if the data doesn't match the schema).

------
styfle
I convinced our BA to use git for internal documentation and meeting notes.

VSTS has a similar online text editor for editing and previewing markdown
files.

I have a web hook that builds the markdown using mkdocs so we can have a nice
web interface for others who do not have edit privileges.

VSTS recently released a wiki feature so I’m considering moving to that
instead of mkdocs.

I think people see the value in wikis but it’s hard to sell git to someone who
hasn’t used it before.

I’m always interested in this type of workflow but the problem that no one has
seemed to solve is the local editing for a draft document for someone who
understands markdown but not git.

~~~
bonesss
> ...the problem that no one has seemed to solve is the local editing for a
> draft document for someone who understands markdown but not git.

.bat or .sh files? :)

A decade ago I was transitioning a small dev shop to Subversion, and daily
user #2 was an non-tech accountant who was a few years away from retirement...

I didn't teach her branching. I didn't teach her merging. I didn't teach her
what a trunk was, or how slicing works. She got two batch files: "Get_Newest"
and "Share_Work", and presto-chango she was contributing user documentation
and keeping our help-files in order inside our development project.

These days, UI competence willing, I'd just install VS Code or Atom with a
markdown plugin and point it at the right GitHub repo. With smart branching
and repo division I think it's a low-barrier way to get people committing via
Git.

------
iamleppert
Don't be taking work out of my wheelhouse now! I learned django templates and
how to make redundant rails models back in 2005 and I don't want the world to
ever change, thank you very much!

Now get off my lawn!

------
wyclif
_While this is a much quicker solution in the short term, an engineer will
have to context switch out of their work, watch the release go out and make
sure nothing goes wrong—that all hurts productivity._

Perhaps it's less stressful and more natural for engineers to view deployment
as part of "productivity." The assumption in these comments and many others
I've seen across the industry is that engineers tend to view any work that
requires context-switching away from coding as impeding their productivity. In
startups you have to wear many hats even if you are an engineer, and it seems
to me that maintaining the view that deployment is a drag on developer
productivity is going to lead to a lot of unnecessary frustration. Why not
just accept deployment as a part of "their work"?

------
ElatedOwl
Certainly an interesting approach

>While this is a much quicker solution in the short term, an engineer will
have to context switch out of their work, watch the release go out and make
sure nothing goes wrong—that all hurts productivity.

Do you think this has caused a productivity increase? I would _guess_ the
additional overhead (unit tests for data files, training sessions for git,
engineers doing code reviews, documentation, etc.) would cause more of a time
suck.

I do like the idea of letting the stakeholder take care of it themselves on
their schedule though without having to code up a GUI. The initial time
investment for a GUI usually isn't that bad for us but the added maintenance
is a huge PITA.

~~~
danpalmer
Yes I think it did.

Take for example a scoreboard with targets on it. The simplest version is to
have a dictionary of datetime to target. We would start with that, show the
metric owner how to edit it, and let them maintain their targets. Won't need
many tests, total time probably 30 mins max to get that solution set up (not
including GitHub training, but that's amortized over multiple uses).

The alternative is building a data model, migration, editing interface which
is probably at least 2 screens (list, edit) and 3 endpoints (list, modify,
delete), needs validation on the input, needs to be put in a menu somewhere,
might need a date input library on the frontend, etc.

This solution would probably end up being at least several hours all-in (code
review, etc), and this is a simple data model that can easily be put in the
database, there are others, with logic for example, that would need a lot more
thought to get into the database. For an interface that might be used
quarterly for 10 mins, it's not worth it.

~~~
ElatedOwl
Don't forget history, because someone will eventually make a mistake and a
finger will need to be pointed :)

In my current org I would still lean on engineers making the config changes,
but if we had a group of more tech-savvy stakeholders I could see this being
useful. I hope you all post an update down the road on this process.

------
dom96
Nice to see something from Thread here. If anyone from the team is looking at
the comments: my SO is eagerly awaiting the launch of the womenswear section.

~~~
danpalmer
Thanks. We’re trying to get our engineering blog off the ground with some
posts lined up for the next few months.

We’re also hiring! [https://www.thread.com/jobs](https://www.thread.com/jobs)

------
pkalinowski
I think the biggest problems usually lie in the company culture.

If you work with people who _pride themselves_ being technology-challenged,
you're doomed from the start.

If they don't fear computers and are open to new solutions - it's a piece of
cake.

------
Myrmornis
That sounds great, but I believe you will find it to be too expensive if your
company grows bigger.

~~~
danpalmer
Maybe. I don’t think we pay per user on GitHub (we might still be on legacy
pricing). I expect we might move to internal GitLab in the long term.

~~~
jxramos
I'm really digging all your engagement in these comments. I also like the
attitude of the Thread engineering revealed in this piece. Very sensible dudes
over there by the sounds of it. I'd savor the day when source control is
common knowledge across many domains.

~~~
danpalmer
We're hiring :)

> Very sensible dudes

We also care deeply about diversity and are trying to improve our gender
balance, so I'd strongly encourage any women or people of other groups
traditionally under-represented in tech who might be reading this to apply,
even if you don't feel you meet the requirements for the job.

[https://www.thread.com/jobs#open-positions](https://www.thread.com/jobs#open-
positions)

------
devmunchies
Github needs a way to limit control to a directory or file in a repo. Its fine
if a non-engineer changes text in a static html file, but they wouldn't know
which files could possibly break tests.

It would also solve a lot of problems with mono-repos.

~~~
danpalmer
It’s not ok if a non engineer erroneously drops a tag making the HTML invalid
though, so I’m not sure directory permissions would be enough.

We just solve this with code review.

------
strangetimes
What the heck are "data files"?

~~~
danpalmer
All sorts. It could be a Python file with a dictionary of datetimes to targets
for that week, it could be a file containing an enum of our suppliers, or
(less a data file) it could be a template for a page on the site.

The point is that they are code, or a file directly loaded in, stored in
source control, rather than dynamic data stored in a database that needs an
editing interface.

------
lurr
What, are they trying to teach aliens? Monkeys? Young children? People who
don't have a common language?

Oh it's just other fully functional adult humans who speak the same language.

So I'm guessing the "how" is "the same way you teach any other person to use
github"?

------
adamscybot
This is a relatively common pattern I've come across over the years. Often
used with translation files by people who are not coders. Sanity checking them
in a pre-commit hook can be useful.

~~~
danpalmer
Yes I've seen it used in translations before, I think that's a perfect use-
case.

