Carolyn Stransky - Life is Hard and So is Learning GraphQL - ReactJS Girls Conference

as you've mentioned my name is Carolyn and I'm a front-end developer based in Berlin Germany I'm working at a company called black lane and I'm also a Mozilla tech speaker but before all of that I worked as a technical writer so I've always been interested in how we learn new technologies and particularly how documentation plays a role in that learning so first I want to tell you a bit about my story of learning graph Juelz so you can kind of understand why I believe that it's difficult it all started when I went to a Berlin j/s meetup and one of the speaker's was a very nice human named Nicholas Burke he talked about this thing called Graff cool which is an open-source framework to develop and deploy server lists graph QL backends they've since pivoted to Prisma but this was years ago so now I had never heard of graph QL at this point but I was in the market for a new technical writing role and I kept thinking to myself like how cool it would be to have a say in how this new technology is documented I saw they had an open position so I applied and I landed an interview as part of the interview process graph pool gave me one week to build a small application and write a tutorial for how to reproduce it so I started thinking about what I could build I already felt comfortable with react plus I could use create react app to save time on development I had to use graph pools graph QL API because it's their own product and finally the Apollo client to connect it all and I'm not really sure if they told me to do it or if it was just either way it was the only like I thought that was the only way to work with graph QL so that's what I did so yeah I finished a few tutorials and had enough of an understanding to QuickStart and build something and I ended up building this cute little image board app and a tutorial to match I know it's a beautiful design my talents are really wasted coding but for a variety of reasons I didn't get the job of course this wasn't the ideal outcome but at the time I was kind of like like I was pretty convinced that graph QL was a phase and it would soon fade away like all of the other programming trends we see pop up on Twitter shortly after I started a new job at a different startup in Berlin that was building a content management system and when we discussed our primary topics that our content would cover for the next year three main things came up static site generators structured content and graph QL and my first reaction was like what the hell this is so neat I was actually kind of mad about it because I was like why are we gonna spend a third of our energy on some sort of like react tooling because that was honestly my perception of what it was but as I started researching again I realized that my understanding of graph QL was so shallow like yes I had built a web app and yes I had quote made it graph QL but I couldn't really explain any of the core concepts and or even really what it was like I mentioned I thought that it was some sort of like random tooling like chalk or like react router so I drove back into learning but it was difficult to know where to go because I couldn't take the same approach that I did with JavaScript because there's no vanilla graph QL it's a spec so there's not just one implementation of it so I ended up asking around like to my friends like what's the best way to learn graph QL and I basically received two types of answers the first was to go to graphical which is in in browser IDE for exploring graph QL and quote try it out but like how do you do this like what day did you use like all of it was a mystery to me or the second option was I could work my way through the official graph QL Docs and naturally as a technical writer I chose that option I ended up on this page and my own story aside this page already causes loads of confusion for many newcomers to graph QL even just look at the term graph QL when I first heard of graph QL I figured it was like d3 or some sort of like programming language that makes charts spoiler alerts it it's not but it's really not that ridiculous of a conclusion to come to if those are the only graphs that you know the QL also gets many people it stands for query language and people tend to associate that with databases because again that's what they know okay back to the main page of the docs so another primary point of confusion comes from that first sentence a query language for your API this is confusing and I would say slightly misleading because one it's not like actually a language in the same way that we tend to think about programming languages it's a specification you can also query anything with it like JSON files CSS etc it's not just api's even if that's marketed as the primary use case okay last thing at least for now but the graph QL Doc's also have this learn page with this introduction to graph QL and this giant sidebar of craft QL concepts that you'll be guided through if you read the introduction and keep clicking next many people myself included take a lot of time to go through all of these because it's like oh well I mean it's here and these are the official documents like the official Docs so it must be really important to know but it's not the thing is is that having a list like this is nice if you're stuck on a particular concept or you know you have this like really specific thing in mind but you don't need to learn all of this in order to be able to use graph QL in a meaningful way so yeah it doesn't make sense but all rants aside this issue is far bigger than the official documentation no matter what source I went to there were a number of blockers that I kept running into while I was learning like unexplained jargon or that it took me a really long time to realize that you can't use single quotes in graphical and it's important to note that all of these were preventable just by adding a bit more care and consideration into the documentation that we're creating and right now you might be thinking like why should I care about this and why are we gonna spend 20 minutes of a react conference talking about graph QL documentation you're not wrong but but the reality is is that this is important because as I realized earlier on in my own story graph QL is more than just some kind of random trend it's becoming more and more intertwined with the reactive community and perhaps more importantly the graph QL ecosystem is at a really pivotal point right now graph QL is now stable and solidified enough to be used in production and to be used by developers across a large variety of skill sets whether it's like the latest graph QL tooling or an open source project that utilizes a graph QL API much of the documentation available doesn't allow for people just joining the industry or even just new to graph QL to understand up until recently graph QL was seen as this more advanced concept but now it's being treated as just like a normal API so anyone who encounters it needs to be able to understand it an excellent example of why this is important is Gatsby so Marcy gave us a nice introduction to Gatsby and at the beginning of 2018 someone from their team mentioned that many of the issues that were being filed on github were about graph QL people thought there was something wrong with Gatsby when really they just didn't understand how graph QL works another point is that graph QL has evolved enough that for the most part the information is out there and available but it's just a matter of finding it because it's scattered throughout the internet or maybe our individual programming communities so I would say it's up to us any of us who know graph QL well enough to document it to be able to connect those dots and create more comprehensive materials for newcomers and because graph QL is I would argue still fairly new and on the rise of being adopted this is really the time that you know we can not only actually fix these problems but also see a real impact in the work that we're doing so I want to run through at least three of the problems that I encountered and consider ways that you know we could better enable our documentation for learning and comprehension well I'll be talking about these in the context of graph QL most of what I'm saying is actually good practice for most technical writings so maybe hopefully it's useful in some capacity to you okay first I want to get this one out of the way because it's my personal pet peeve there seems to be this idea out there that graph QL both reduces the time you need to spend documenting your API and also the amount of documentation that your application actually needs and that's just not true yes one of the reasons that graph QL is so great is because there is this interactive piece to it for example if you're not sure what data is exposed by the API and you're on an interface like graphical the tool will autocomplete what's available for you there are also these auto-generated explanatory Docs based on the three main entry types into a graph QL schema query mutation and subscription but while these may ease our lives as developers they aren't very human and they don't offer that guidance that we often expect or maybe need documentation to provide there was this talk by Andrew Johnston at API the docs where he explained that this type of documentation is great after you understand the domain area in the business cases and you've built some confidence making queries and mutations but without more detailed documentation that covers the conceptual materials you're not going to get there and there's one more quote that I find really fitting Chris Ward who's a technical writer based in Berlin says that documenting API endpoints explains how individual tools work explaining how those tools work together is a whole other area of documentation effort he actually has an entire article on this topic I've linked it you can't see it but it's linked under here all of my sources are you can find them later I swear but anyway okay anyway so the basic idea is that you still need documentation efforts for things like onboarding guides or tutorials to explain how those general concepts tie into your specific use many products that rely on graph QL as part of their core business have begun to do this and they do it pretty well so since we're talking about Gatsby in their issue with graph QL earlier let's use them as an example so now if you go to their Docs they actually have an entire section devoted to what graph QL is why they specifically chose it to query their data and how it works in the context of gatsby which gives you a good frame of reference when you're beginning to learn the next issue is another personal one because it took me like on a reasonably long time to realize that graph QL wasn't actually a JavaScript thing and to understand why graph QL is so tightly woven with the JavaScript community you need to understand a bit of its history one of my favorite favorite descriptions of graph QL came from SC Barras where he described graph QL as quote another in a line of technologies that were emerging from the hipster catacombs at Facebook and because it was introduced by Facebook and particularly at a react conference people naturally associated the two as JavaScript developers or at least people who are interested enough in JavaScript to be sitting here today this actually works to our advantage it's great by far the JavaScript community has produced the most content tutorials and how to's around graph QL and like I said no complaints it's pretty nice but that being said it's important to realize and recognize that graph QL is actually framework agnostic and you can implement a graph QL API using a bunch of different programming languages this isn't even close to the full list we need to give more visibility to this fact especially when we're creating introduction and onboarding materials for example I really like that on the learn tab of the graph QL Docs it points you right away to a page with a list of libraries to help you implement graph QL in many different languages and that page itself provides a thorough list of server libraries tools services etc to help get you going the last major issue that I want to address right now is that the graph QL community throws out a lot of assumed knowledge and a lot of really specific terminology and acronyms and this isn't necessarily done maliciously what often happens is in any type of technical writing or technical documentation is that while you're writing it you'll tend to write it as if you're talking to yourself but the problem is is that first time users won't have that same frame of reference so any unexplained term or skip step in the process can really destroy that learning journey for your user and this is especially the case for anything graph QL related projects using graph QL need to explain it much more thoroughly or at least link to other resources that can because for many readers it'll be a completely new concept and to be honest I think it's going to be like this for at least the next couple of years what you need to remember is that no matter how intuitive you think your tool is or how advanced your users might be everyone starts somewhere and everyone is a beginner at some point one way to prevent this disconnect is to include any prerequisites for a tutorial guide projects at the very beginning this way everyone starts off on equal footing and bonus points if you can link to any materials that might fill those knowledge gaps one resource you could link to is Apollo's graph QL glossary it's a comprehensive list of important graph QL words and acronyms and honestly I think it's my favorite graph to over learning resources that come out of 2018 besides Eve's book of course or if you want to go a bit higher level Facebook's graph API documentation is another great resource to reference they cover commonly misinterpreted definitions like nodes edges fields quite well and they give a good overview in terms of thinking in terms of graphs and in addition to these more fundamental issues I want to go through a few quick tips about documenting graph QL related projects so be confident with your definitions even today I still see new articles or tutorials being published where they define graph QL using phrases like from my understanding or I believe it's this way and this brings no value because it really like shatters your own credibility as the person who write like who's writing it and it just further confuses people because they're like it's really the definition like I'm not sure the information is out there and available you just need to find it and link to it second and Emma touched on this in her talk earlier like when you introduce a new tool or service be sure to say what it is or at least provide a link to their Docs and maybe explain why you chose it try to answer like what problem will this - we'll be solving and why do we need it and finally be transparent when you know there's a specific use case that doesn't work just say something like you'll save people headaches in the long run and I really promise you it will not destroy your business and unfortunately this talk isn't long enough to you know really cover the intricacies of documenting graph QL concepts or how to better explain the core functionality although I'm happy to talk about that later if you want but if you are new to graph QL I do want to leave you with a few free resources available to start how to graph QL comm offers a pretty solid overview of the concepts plus it walks you through implementations and a bunch of different programming languages the only prior knowledge necessary is a rough understanding of what an API is and understanding how client-server communication generally works how to graph Q out as it is today is pretty back-end heavy there's literally only one front-end tutorial so if you're a front-end developer I'd recommend starting here to get the basics down and then moving to Peggy raises a front-end developers guide to graph QL she did this talk at fluent comp last year but it's hidden behind like a safari paywall and now I feel bad that you can't see the links but I'll tweet the slides later so you can find the links fortunately though she created github repo that I would have said we're linked they're perfect and with her slides and resources for the talk and she also wrote an accompanying article for CSS tricks with the same title because she works at Apollo she uses tools like the Apollo server and Apollo client in her examples but don't let that intimidate you the concepts are there and plus she provides example apps that are in react angular and view so it's that you can reference and maybe compare between them if you are the type that does like to immediately go and try something out I'd recommend experimenting with the github graph QL API it's data that if you're using github regularly you're probably already familiar with so it might be a bit easier to comprehend how to fetch the data and how that data is being structured there's also the community resources on the official graph QL Docs it has a variety of resources from newsletters to podcasts that you can check out it's not an exhaustive or particularly diverse list but it's a way to get going and finally some shameless self-promotion Sarah Vieira and I what we had this idea of building this website that incorporates this idea of use cases and learning journeys into this kind of choose-your-own-adventure format admittedly it's still super messy see there's still like a lot of to dues but if you can file it under like things I'd love to give more time to but life it gets in the way of open source but please if you have any ideas or resource suggestions check it out send me a message and there's just one last thing before I II I want to say before I get off the stage has anyone here heard of monads okay okay I literally just did so it's okay I guess there's some sort of like functional programming thing but they're infamously difficult to explain in fact this might be hard to read but it says once you understand monads you immediately become incapable of explaining them to anyone else and if you take away anything from this talk please let it be this please don't let graph QL become the new monads thank you [Applause]

Channel: Tech Talks YLD

Views: 643

Keywords: reactjs girls, reactjs girls conference, conference, react conference, graphql, carolyn stransky

Id: ADudeU3agu0

Length: 20min 29sec (1229 seconds)

Published: Tue May 21 2019