18 ms·
How and why we teach non-engineers to use GitHub at Thread
- pkalinowski 9y agoI 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.
- maxxxxx 9y agoAren't they using GitHub for what traditionally would have been done with a CMS?
- danpalmer 9y agoYes, 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 9y agoBut 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.
- danpalmer 9y agoFair point. Currently we don’t encourage this across the whole company for copy changes. We mostly teach this to specific people who need to edit specific data.
- nkrisc 9y agoThen 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 9y agoBut you gave everyone commit access...and she is doing her job.
- sgnl 9y agoIn your example, her job is an Accountant. She can aspire to be a writer but not on company time.
- busterarm 9y agoBut 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 9y agoBecause 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 9y agoMost CMSes suck at versioning and in any case, you create massive headaches for yourself by having multiple versioning systems that need synchronization on the same project.
- strangetimes 9y agoWhat the heck are "data files"?
- danpalmer 9y agoAll 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.
- golemiprague 9y agoMost databases these days got some automatic admin interface which let users edit the data, usually with some roles and permissions to what people can or can't do. I don't see the big advantage of letting people edit files directly if all they need to change is data.
- jajern 9y agoI guess aren't all files "data files"? When I think data files I think of a file that contains data points (CSV, tabular, etc).
- iamleppert 9y agoDon'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!
- adamscybot 9y agoThis 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 9y agoYes I've seen it used in translations before, I think that's a perfect use-case.
- Myrmornis 9y agoThat sounds great, but I believe you will find it to be too expensive if your company grows bigger.
- exabrial 9y agogitlab, or self hosted git?
- Myrmornis 9y agoThere's no mention of Gitlab in the article. Github private repos for business and Github Enterprise are the same price: https://github.com/pricing https://github.com/pricing
- danpalmer 9y agoMaybe. 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 9y agoI'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.
- learc83 9y agoInstead 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).
- jopsen 9y agoyou won't get global versioning, issue integration, PRs, etc..
- learc83 9y agoYou're essentially replacing a database and a CRUD interface, which doesn't have any of those features either. I can't see how any of that is worth the extra time spent teaching git, or the extra complexity that comes along with merging your code and data into one repository.
- danpalmer 9y agoA python file with a list in it, is significantly simpler than a remotely stored data file, which brings with it parsing, error handling, issues developing offline, and still requires AWS permission understanding and some S3 teaching. Git, and GitHub, at the level we teach them, are not very complex.
- codemac 9y agoIt 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.
- learc83 9y agoThey're still teaching them about branches, pull requests, commit messages, merging, and build statuses. Not to mention that mixing data and code into the same versioning system adds complexity that I don't think is maintainable. There is a reason we tend to version data separately from code.
- dom96 9y agoNice 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 9y agoThanks. 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
- devmunchies 9y agoGithub 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 9y agoIt’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.
- madeofpalk 9y agoI’ve been happy with using PRs and CI to avoid this problem.
- bonesss 9y ago> Github needs a way to limit control to a directory or file in a repo. Monolithic version control systems tend to do this very well. In my head a distributed system like GIT really needs awesome and integrated sub-module features to make it go around. Last I tried this was in-theory easy but in-practice hard with Git. As-is I believe separate repos or custom commit scripts/hooks might get you farther :/
- tootie 9y agoSquare 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.
- busterarm 9y agoWe did exactly this and it's been great. We started with our content editors just using WordPress and on one project we transitioned them to using Kramdown inside WordPress to build a Jekyll site. Once they were familiar with both, the next project we gave them Jekyll and they can enter content and meta info via Forestry. Forestry has been a big help to us with support and quick turnaround for feature requests and it's been pretty smooth-sailing for our content team. For internal documentation/knowledge-sharing, we started a MediaWiki.
- danpalmer 9y agoYep. We use MediaWiki for internal documentation, particularly for the support team, and we use FeinCMS (a Django CMS/blogging package) for our “tips” blog. Unfortunately neither of these work for obscure internal data models that we have, or the time to integrate one isn’t worth it for an A/B test we might throw away next week (although if we decide to ship the A/B test we would take that time to integrate a CMS or add an editing interface on top of our DB).
- busterarm 9y agoI actually do like A/B tests in Git, especially if you have great commit messages and tags around this, because there really should be a historical record of all experiments that have been run. Throwing them away is a tremendous waste of knowledge. We found this to be true with our marketing and that was the reason for the push to setting up a Wiki. Even if we don't retain code around an experiment, we have a documentation format for recording what we made, what our expectations were and our results.
- ElatedOwl 9y agoCertainly 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 9y agoYes 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 9y agoDon'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.
- crdoconnor 9y agoSince 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 9y agoThanks, 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 9y agoShouldn'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).
- kaikai 9y agoMapbox 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 9y ago> 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 9y agoOf 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.
- styfle 9y agoI 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 9y ago> ...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.
- jbergens 9y agoWe tried the markdown support in TFS but it was not what we wanted and then we created a small tool using a static site generator. It builds the documentation site after someone pushes new content to the documentation folder. This worked well enough for all devs and some non-devs. I would like to have something like NetlifyCMS but locally stored. https://www.netlifycms.org/ https://www.netlifycms.org/
- wyclif 9y agoWhile 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"?
- lurr 9y agoWhat, 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"?