A few months ago I joined the documentation team at Semmle (the company behind LGTM) as an intern. I arrived in the Semmle Oxford office, had a brief induction and tour of the building, and then quickly settled in to my new desk and extremely comfortable desk chair. Incidentally, my desk was right next to one of the company snack cupboards. Having to resist the tempting snacks on display was one of the greatest challenges of my internship. (Who knew that "quadruple chocolate cookies" existed? I definitely couldn't resist those.)
Introduction to QL
Of course, responsible snacking wasn't the only challenge. I had a lot to learn before I could start writing. A few months ago, I only had a vague idea of what LGTM and QL were and, unlike many Semmle employees, I did not have a strong background in theoretical computer science. As a mathematics undergraduate I was familiar with subjects like logic and set theory, but I had very little practical programming knowledge. This meant that I had a lot to catch up on, but also that I was in a good position to judge whether the existing documentation was accessible enough to an outsider.
It took me a while to find a suitable introductory topic, so I just started experimenting with the example queries in the query console. Even without understanding the code, I could tell that QL would be extremely useful for analyzing projects. After spending a few more days reading through the QL language primer and the language-specific tutorials, I began to fully appreciate the power of QL. However, despite starting to understand some of the subtleties of the language, I still struggled to use QL in practice. The language-specific QL tutorials did a good job of introducing the extensive QL language libraries, but there weren't many language-neutral exercises that helped me learn the QL syntax.
New QL tutorials
My task was to update and improve the QL documentation. I wanted to create some beginner topics that provided a gentle introduction to QL. I also wanted to include more practical exercises and examples to help people get used to the QL syntax and practice writing their own queries.
First, I rewrote the Introduction to the QL language topic to be more accessible for beginners. The original version started with:
This topic is intended to serve as an introduction to QL for users with a background in general purpose programming as well as in databases.
That sounded pretty scary to me! I moved that advanced discussion to About QL and instead added basic examples and exercises to the introduction.
Second, I created some additional beginner tutorials that use QL in an interactive and lighthearted way. Since QL is a logic language, the idea of a "QL detective" using logical deductions to solve crimes seemed appropriate. I had a lot of fun thinking of semi-plausible situations in which to introduce key QL concepts.
Try it yourself
Hopefully the new QL detective tutorials will encourage you to explore QL and the query console too. You don't need a lot of time or experience to learn QL, just give it a go! If you don't know where to start, here are my suggestions:
- Start with the Introduction to the QL language.
- Work through the QL detective tutorials.
- See the Learning QL page for a summary of available learning resources.
- Look at the QL language handbook for an overview of the language.
Of course, there is much more to QL than I could fit into my tutorials! If you want to find out more about the underlying structure of QL, there are plenty of academic resources and detailed topics to explore. For example, once I'd mastered the basics, I was intrigued by the advanced topics and spent some time reading about those. I was lucky to have the QL experts nearby and they always seemed strangely excited to discuss things like "monotonic aggregates" and "abstract classes" over lunch.
Now that I've reached the end of my internship, it feels appropriate to document the internship itself. The past few months made me appreciate the importance of good documentation and realise quite how much work goes into writing it. Up until a few months before my internship, I'd never even heard of technical writing let alone considered it as a potential career path! It certainly helped that the existing "Doc team" at Semmle made me feel very welcome: I got invited to meetings and team lunches and received lots of helpful feedback.
QL and LGTM have already had a big influence on software—from displaying small bugs in personal code, to detecting severe security vulnerabilities in major open source projects—and I'm sure they will continue to make software better around the world.
Hopefully I can later look back at the small part I played in spreading the joy of QL and proudly say it "looks good to me".
Note: This post was originally published on LGTM.com on September 28, 2017