#74 - Rapid Web Apps Development With Anvil & Importance of Product Documentation - Meredydd Luff

 

   

“Documentation is content marketing. If your docs don’t summarize what your product is actually about, you’re going to have a rough time getting anybody interested."

Meredydd Luff is the founder of Anvil, the platform for building web apps with nothing but Python. In this episode, Meredydd shared his story starting Anvil and his point of view on the latest Low-Code & No-Code movement and whether it would affect the demand for developers. He touched on the importance of domain experts having the ability to develop software and how tools like Anvil could play a part in supporting them to translate their ideas better. In the second half of the episode, we discussed the importance of product documentation and how it also plays a major part in content marketing. Meredydd shared his tips and best practices for documentation, including how to create thriving online Q&A product forums.  

Listen out for:

  • Career Journey - [00:05:17]
  • Anvil Story - [00:09:16]
  • Low Code / No Code - [00:12:26]
  • Domain Knowledge Coder - [00:18:08]
  • Demand for Developers - [00:22:37]
  • Importance of Product Documentation - [00:25:42]
  • Documentation is Content Marketing - [00:29:16]
  • Online Q&A Forums - [00:33:18]
  • Developer Advocates - [00:36:55]
  • 3 Tech Lead Wisdom - [00:39:43]

_____

Meredydd Luff’s Bio
Meredydd Luff is the founder of Anvil (https://anvil.works), the platform for building and deploying apps on the web with nothing but Python. He’s particularly interested in expanding access to code, and has a PhD in building usable programming systems.

Follow Meredydd:

Mentions & Links:

 

Our Sponsor - Skills Matter
Today’s episode is proudly sponsored by Skills Matter, the global community and events platform for software professionals.
Skills Matter is an easier way for technologists to grow their careers by connecting you and your peers with the best-in-class tech industry experts and communities. You get on-demand access to their latest content, thought leadership insights as well as the exciting schedule of tech events running across all time zones.
Head on over to skillsmatter.com to become part of the tech community that matters most to you - it’s free to join and easy to keep up with the latest tech trends.
Our Sponsor - Tech Lead Journal Shop
Are you looking for a new cool swag?

Tech Lead Journal now offers you some swags that you can purchase online. These swags are printed on-demand based on your preference, and will be delivered safely to you all over the world where shipping is available.

Check out all the cool swags available by visiting techleadjournal.dev/shop. And don't forget to brag yourself once you receive any of those swags.

 

Like this episode?
Follow @techleadjournal on LinkedIn, Twitter, Instagram.
Buy me a coffee or become a patron.

 

Quotes

Anvil Story

  • It’s just such a horrible environment. This is such a productive medium. There is no good reason to put those obstacles in the way of someone who just wants to build something that can be usable by an end user. You should not have to go through that obstacle course to make something with a button that does something useful when you click it.

Low Code / No Code

  • The problem with web development, the thing that makes it so difficult for anybody to learn a little bit of programming, then pick it up and produce something that’s actually useful to end users is the amount of complexity in getting anything working on the web.

  • We have been telling computers what to do for about the last 75 years, give or take. In that time, nobody has found a better way to tell a computer what to do than to write texts in a vaguely algebraic programming language. It just seems to be the best we have. Given that we are telling a computer what to do, why not just use that?

  • The reason that web development is so complicated is not the development, it’s the web.

Domain Knowledge Coder

  • It’s always been true that people with the domain knowledge are really, really important.

  • One of the biggest challenges indirectly created by the present web development landscape is that the most efficient way to build something that solves your problem is to have it done by somebody or some people who understand the problem directly themselves.

  • The magic ingredient to unlock this value that is software eating the world is to have a deep understanding of the problem that needs to be solved, and the ability to make it happen in the same skull. Because if you have that, then you can do your iterative design process.

  • Whereas if you are doing the classic thing that happens when somebody with some domain knowledge contracts a programmer to build something, they specify something, specifications are necessarily incomplete, it comes back, and it’s not quite the right thing. And the iteration is incredibly slow and incredibly expensive.

  • So having a person who understands it, be able to build it is really important.

  • One is that as it’s become more apparent to everybody, that software is how we get a lot of things done, there is more pressure. And more people have been burnt by the experience of, for example, hiring external consultants, or trying to get some software built when that knowledge isn’t in the same skull.

  • I think it is good that people are noticing that, frankly, the programming tools we have built are not fit for purpose.

On Demand for Developers

  • It remains astonishing to me how much leverage just being able to build an application is.

  • There is an industrial revolution happening of some sort. But things are still shifting in the direction of doing things online with custom-built software. We are currently the only set of people who could make that happen. I think it is right for that set to expand. I think that additional tooling so that people who have not put their entire careers into learning to be developers can still get something off the ground is going to be part of the answer. And I think that expanding the set of people who can do what we do is going to be part of the answer. And I think frankly, those are both good things.

  • The sheer leverage that you can write a fairly small piece of software, and unlock an enormous amount of value in the world, means there’s still a pretty bottomless demand for what we do as far out as I can forecast.

  • Copilot is currently in the state of being a gimmick. The code it produces is usually right. But because it’s usually, you end up with needing somebody who actually knows how to code, and who can read the code that is generated to check that actually does what you want it to.

  • This is true in all forms of applying neural networks, because they’re black boxes. They’re often very inconsistent and when they fail, they fail in weird, unpredictable ways.

Importance of Product Documentation

  • Most software, the ideal is that you’re not going to need a manual. Developer tools, because they have such complex interfaces, and your interface is offered in a textual API, you’re going to need documentation.

  • If you’re building a developer tool, whether that is a library, you’re hoping somebody will npm or pip install and use, or an API that you want people to call, or develop a platform like Anvil, your user interface is your documentation. That’s what the developer is going to be staring at while they’re using it. They’re going to be looking at your docs and their code and that’s it.

  • People systematically under-invest in developer documentation. Because all the shiny demos, of course, don’t involve looking through the documentation to find out what you should be doing next, because they’re all on some happy path. But in practice, the actual use of your product involves a lot of staring at documentation.

  • If you think about the life cycle of a developer finding and develop a product, they need to discover that it exists to begin with. They need to decide that it’s actually useful - it actually solves that problem. They need to do this. They need to be able to work out what it is even, and your documentation kind of defines that. And then, of course, they need to do the classic forms of learning how to use it and solving the problems they will encounter along the way.

  • Documentation is content marketing. Because if you’re solving a real problem out there, then somewhere there is a developer punching into Google. The question, how do I do exactly what your project does? Your documentation is literally the answer to that question. And so they should be finding it.

  • If your docs don’t summarize what your product is actually about, you’re going to have a rough time getting anybody interested.

Documentation is Content Marketing

  • [Daniele Procida] divides a documentation into four categories. You’ve got tutorials, so the step-by-step guides to learning how to use something. The how-to guide, which are step-by-step guides to accomplishing a particular practical task. The explanations, which is how and why does it work the way it does. And then the reference documentation, which is comprehensive and says everything about the machinery and how to operate it.

  • I have some small disagreements with him. I think it’s useful to separate the difference between API documentation–what functions are they? What arguments do they take? What’s this particular thing do–and reference documentation, which tells a little bit more of a story, A causes B causes C or A then B then C.

  • If you’re looking at SEO and content marketing, how-to guides are the most SEO of all there, because they are the things that somebody is actively trying to do. And so, if you are looking to make yourself more discoverable, then finding a bunch of classic use cases, and writing how-to guides, or “how to do X with your product”.

  • [Demo] is also marketing because you’ve shown them how to do a cool thing. You’ve actually given them a mini tutorial.

  • There are a lot of tasks that we traditionally think of as documentation that matter much, much closer to the start of the funnel than we, as developers, typically think. We think of them as problem-solving tools and they are so much more than that.

Online Q&A Forums

  • I don’t really think of a Q&A forum like that as a marketing channel so much. I think by the time somebody is searching Stack Overflow for the particular problem they’re having with your project, they’re already using your project. Q&A forums have a much more powerful role. They are used a bit in things like evaluating frameworks.

  • We self host our own website, which I kind of recommend if you can, because Stack Overflow is famously a bit arbitrary and has a very strong set of norms, and you might not want your user community to be shaped by those norms.

  • The biggest advantage of Q&A forums is that they are a user generated set of bug reports against your documentation. Anybody who is asking a question in your Q&A environment is stuck on something. That probably means that your documentation hasn’t pointed them in the right place.

  • Even better than that, whether it is provided by community members or by developers themselves of the underlying project, the answer in the Q&A forum is a patch against that documentation. Because what it means is that people can search for the error message they’re seeing, and they will see an authoritative answer, even if the documentation doesn’t actually answer that question yet.

  • But that only works if you do it in a publicly searchable space. If you do it somewhere like Stack Overflow, you do it somewhere like a forum that is browsable by anonymous user, if you just do that in a Discord or Slack channel, you get the bug reports as a developer. You find out what people are asking questions about. And don’t get me wrong, that’s really valuable. But then your answers disappear into the ether. They’re not searchable. They’re behind some kind of wall and they scroll away into the never, never.

  • Whereas if you use a publicly visible and searchable Q&A environment, it forms almost a sixth pillar of your documentation. You’ve got your examples. You’ve got your tutorials. You’ve got your how-tos. You’ve got your reference. You’ve got your API documentation. And then you’ve got the Q&A, which is the sort of self-healing catch-all. Your documentation becomes self healing.

  • Don’t use Slack. Don’t use Discord. Do use Discourse, annoyingly similar names, or Stack Overflow or something else.

  • Having a Q&A forum is vitally important. It provides not just a signal to your potential users that your community is alive and kicking. But it makes your documentation self-healing, and it allows people to report bugs and patches against your own documentation.

Developer Advocates

  • If you are a developer in a developer focused company, that person’s job title is likely to be developer advocate.

  • It is possible to have something like a community manager who’s just making sure things are flowing, making sure questions get answered, but really, you want the people doing this to be programmers, to be software developers who can actually answer questions, provide authoritative answers. Not just recognize that a question is getting answered, but make sure a question is getting answered well.

  • You need to give them the authority, the loud enough voice to speak on behalf of your users, as well as on behalf of you to your users. It’s one of the reasons the community likes the term developer advocate. The advocacy goes both ways.

  • But basically, you should be listening to them. They should be important people in your team. They should be people important enough to sort of grab the dev team by the ears and swivel their heads and force them to look at a problem that people are experiencing. Because developers love not looking at problems.

  • The trick is to make sure that people are actually in contact with the people who are having the problems. The closer you can get that process to the developer team, the better.

3 Tech Lead Wisdom

  1. Lead by example.

    • If you are doing the classic Tech Lead role, you are on the border of technical to managerial. You’re coming from the technical side. Then you lead by example. That technical competence will earn you trust for the other things that you want to do.

    • If you want to make a change, then this is really handy to have built trust with technical competence. That’s not the only way to build trust. I’m sure other people have other routes in being a really good manager can build confidence in you when you are making a change that has technical implications.

  2. Brute force and empathy.

    • I’ve described our management style as brute force and empathy, which is to say, the most important part you can get away with not knowing what you are doing is if you are just very human about it.

    • The most important thing is these people are people, and if you would like to understand what is going on in their heads and to have them happy or satisfied as well as going in the direction that you want to do, you can not have a lot of management theory. But if you have the empathy to be looking inside your colleagues' heads, and caring about how they are feeling.

  3. Give junior people a chance.

    • Don’t overlook the junior folks just because the CV doesn’t have the right number of lines of code in.

    • You should have a mental thing in the back of your head that any hiring process that would not hire «insert name here» is broken.

Transcript

[00:01:23] Episode Introduction

[00:01:23] Henry Suryawirawan: Hello to all of you, my friends and listeners. Welcome to another new episode of the Tech Lead Journal podcast with me your host, Henry Suryawirawan. Thank you for spending your time with me today, listening to this episode. If you’re new to Tech Lead Journal, subscribe and follow the show on your podcast app, and join our social media communities on LinkedIn, Twitter, and Instagram. And if you have been regularly listening and enjoying this podcast and its contents, will you support the show by subscribing as a patron at techleadjournal.dev/patron.

My guest for today’s episode is Meredydd Luff. He is the founder of Anvil, a platform for building and deploying apps on the web with nothing but Python. In this episode, Meredydd shared his story starting Anvil and also shared his personal point of view on the latest craze in the industry, which is the low-code and no-code movement, and what he thinks, whether the low-code and no-code tools would eventually affect the demand for developers. Meredydd also touched on the importance of domain experts having the ability to develop software, and how tools like Anvil could play a part in supporting those experts to translate their ideas better.

In the second half of the episode, we discussed the importance of product documentation and how it also plays a major part in content marketing. Meredydd shared the different types of documentation, his tips and best practices for building good documentation, including how to create thriving online Q&A product forums.

I enjoyed my conversation with Meredydd, learning about Anvil and where it stands amongst the many low-code and no-code tools these days, and also learning about how to build a good product documentation. If you also enjoy and find this conversation useful, I encourage you to share it with someone you know who would also benefit from listening to this episode. You can also leave a rating and review on your podcast app or share some comments on the social media about what you enjoy from this episode. So let’s get our episode started right after our sponsor message.

[00:04:23] Introduction

[00:04:23] Henry Suryawirawan: Hello, everyone. Welcome back to a new show of the Tech Lead Journal podcast. Today I have with me, a guest named Meredydd Luff. He’s actually the co-founder of Anvil, a platform for building and deploying full-stack web apps with nothing but Python. We’ll be probably talking about Anvil later on in the conversation. But today we are also going to talk a lot about documentation best practices. How would you document your product or services? If let’s say, any of you are building products or services out there that you want people to use, either for open-source or for commercial, Meredydd today will be talking a lot about how can we get our documentation so that other people are interested to use your products. And Meredydd actually has a PhD in usable programming systems. Maybe later on, you can share that as well for us. What is usable programming systems? And yeah, looking forward to have this conversation with you, Meredydd.

[00:05:13] Meredydd Luff: Excellent. Well, I’m glad to be here. So much to talk about already.

[00:05:17] Career Journey

[00:05:17] Henry Suryawirawan: So yeah, in the first place, maybe can you introduce yourself, telling us more about your background, any turning points or highlights in your career?

[00:05:23] Meredydd Luff: Sure. So my name is Meredydd. I am co-founder of a company called Anvil. We make our platform for building web applications. I got into programming when I was very young. I was fortunate to be introduced to it by my dad, who’s an electrical engineer. I first started out with things like QBasic and Visual Basic, which were these really great on-ramps, because for a kid to discover that this thing was actually greatest toy that he’d ever met, it was really great to have these environments where just a little bit of programming, each new piece of knowledge unlocked so much of tangible experience. If you’re sitting there on a DOS computer and you can draw lines on the screen, yeah, you are overjoyed because this is essentially kind of like any other program that’s already running on your computer. And then suddenly, I could put Windows on the screens and make things that other kids in school could use. They could actually click on menus and icons and buttons. It was like a real program, and I really got the bug. Only really a few years later worked out that this was actually a thing that you could be when you grew up.

In the meantime, I did my degree in biology rather than computing, because I knew this would always be part of my life. So I decided to take the opportunity and studied neuroscience in the end. And then gave into my destiny and did my PhD specifically, it was around usability of concurrency and parallel programming, which is an area that’s absolutely full of bear traps. It was a fun way of exploring a piece of computing I hadn’t really encountered before. But then I did hang around in academia. Did some consulting projects. Was involved in a startup doing mobile messaging in the Philippines, and ended up founding Anvil, and that more or less takes us to current.

The question is more which parts were not turning points? I feel like looking back. Actually, there are a three lines here, which is that I had the magical experience of picking this thing up and deciding, hey, this is really fun to use. And then nibbling away at the back of my brain, was a desire for other people to get the same experience. And so whether I was simulating hypothetical chip designs in my PhD, or building Anvil, or doing undergraduate teaching, the through line is this is the best game on earth and you should be able to play too.

[00:07:42] Henry Suryawirawan: Yeah. So I was about to ask. So you started from a biology degree, right? Which is something maybe a little bit unexpected, if you can tell, from most of the programmers these days. So what will be some of the key things that you learned from biology that you can actually transfer to computer related work?

[00:08:00] Meredydd Luff: I’m sorry to give a disappointing answer, because people are always expecting some kind of wisdom in fusion. But biology is such a different sort of thing to computing. It’s why I found it refreshing. Because I was your prototypical teenage larval-stage nerd. I had spent lots and lots of time with computers, and now for something completely different was really what I needed between the ages of 18 and 21. Biology is, everything is contingent. The other end of the spectrum, you’re learning the deep, fairly elegant underlying principles of the universe. If you’re playing with biology, you are learning a whole bunch of contingent facts about the way evolution happens to do it. It is fascinating and there is an enormous amount of complexity. People talk about the complexity crisis in computing, the way that these machines are too big for a person to understand. We ain’t got nothing on biology, because any given slice of it is too big for absolute experts in that domain to understand. Which is very different from computing, which is we built this thing from scratch. Fundamentally, it is understandable. It’s refreshingly different perspectives, actually. And I always knew I was going back to it. So for me, biology was something as a break. Sorry to anyone who’s listening here who interacted with me professionally during that time.

[00:09:16] Anvil Story

[00:09:16] Henry Suryawirawan: So Meredydd, if you can go to the Anvil story. What made you decided to co-founded Anvil? As you mentioned in your career journey, you have these turning points from biology, doing consulting, working in startup, and now building a product that seems to be for people to create product easily with just using Python. So sounds like a QBasic last time, but in a different way or format?

[00:09:39] Meredydd Luff: Absolutely. So the background of this is that, if this has been your interest for your life, you’ve thought it was an amazingly fun toy. You’ve been very glad of your opportunity to pick it up and play with it and work out how it works. And then you go and do a PhD that’s concentrating on building usable stuff, which means that you’re concentrating on all the sharp edges and all the things that make certain sorts of programming extremely human unfriendly. And then one of your best friends you’ve known since the first day of university is also doing a PhD in human computer interaction. Your sort of over afternoon tea conversations are going to involve a fair amount of ranting about human hostile computer systems. And you know, every nerd loves a good rant.

At a certain point, having really plumbed the depths of ranting about how these days everybody was using systems like the web where everyone was building for the web. And suddenly, you’ve gone from what we knew in the late nineties, where anybody with a little bit of programming knowledge could pick up a tool like Visual Basic, and produce something useful that could be used by end user. Because it was just a Windows application like everything else that was being used. We went from a world like that to a world where you must be this tall to ride this ride bar. Only this tall is I need to know JavaScript and HTML and CSS and Python and SQL and React and Redux and Bootstrap and Flask and SQL Alchemy and Webpack and AWS and Git, and I’ve already ran out of fingers. It’s just such a horrible environment. This is such a productive medium. There is no good reason to put those obstacles in the way of someone who just wants to build something that can be usable by an end user. You should not have to go through that obstacle course to make something with a button that does something useful when you click it.

This frustration had been bubbling along in the backs of our minds, and eventually, somebody ought to build something a little bit like Visual Basic for the web. Since nobody seems to be getting on with it, we decided that it might as well be us. This was very much started as a fun project. It was at Ian’s dining room table. We would doodle around with, okay, what should this thing look like? Or let’s try building a little bit more. And then we got the bit between our teeth, and it started going further and faster. Eventually, we put a link to it up on Reddit, and they bit our hand off. Suddenly, we went, “Oh, I see this really is a real business. There are actual people who would find this useful. It’s not just a project we find cool.” From there on, we stopped doing it in sort of odd days, we called from the rest of our jobs. We ramped ourselves up to full-time and made proper business of it. So we’re now a bootstrapped startup based in Cambridge with offices and employees, you know, almost like real boys.

[00:12:26] Low Code / No Code

[00:12:26] Henry Suryawirawan: So I think if I can relate this Anvil with the recent low-code and no-code movement. People these days are talking a lot about all these new technologies. So, is Anvil one of the low-code, no-code platform?

[00:12:39] Meredydd Luff: Oh, okay. So let’s talk about the nature of the problem here. To be clear, the problem with web development, the thing that makes it so difficult for anybody to learn a little bit of programming, then pick it up and produce something that’s actually useful to end users is the amount of complexity in getting anything working on the web. So people come along, they look at this problem and they go, well, clearly, you can’t expect a, let’s say, manufacturing engineer who has spent their valuable years learning about manufacturing. They haven’t been learning about this unwieldy stack of software. They might reasonably want to create something that is usable in their domain in manufacturing. You can’t reasonably expect them to pick up this huge mess of tools. And some people look at that and say, oh, well, what that means is that development’s too hard and let’s take away this complicated coding stuff and give you a set of flowcharts with boxes and arrows. You can click and drag those things together, and then you can create an end user usable application without writing any code. Thus, the no-code movement (was) born.

Then there’s a bit of a problem. Because it becomes rapidly apparent that basically anything you have dragged and dropped together out of flowcharts is going to have some serious omissions. You’re going to find yourself wanting to do something that your environment doesn’t let you do. This is an awful feeling because, by this point, you’re already trapped. You’ve already got halfway to what you want, and then you discover that the other half is simply impossible, and that is an awful, awful, awful experience. So, this movement really ends with “Fine, okay, okay. What we’re going to do is we will give you an opportunity to when you run out of things that this platform lets you do, you can drop down and write a React component.” Now, you can do anything you want and that sort of tautologically true, because when you run out of things that this system can do, you can just drop down to the mind bogglingly complex tool set. So they say, “Okay, well, we’re not actually no-code. We’re low-code.” You don’t have to go and build a full React component often to do what you want.

Of course, it doesn’t matter how often you need to do it. If you need to know how to do it, then you need to know how to code or have access to somebody who can code using all these complicated web systems to get anything substantial done. And so, strictly speaking, it’s better than getting completely stuck in a no-code environment you can’t do anything else with. But if you zoom out here, you haven’t really avoided the problem. You’ve put people in an environment where they are going to get themselves stuck, and they’re going to end up either with Cthulu’s own flowchart, or they’re going to end up with something that literally can’t do what they wanted. Either way, actually, by the time you’re pushing the system that far, you’re having to think computationally, anyway. You might as well be writing code.

We have been telling computers what to do for about the last 75 years, give or take. In that time, nobody has found a better way to tell a computer what to do than to write text in a vaguely algebraic programming language. It just seems to be the best we have. Given that we are telling a computer what to do, why not just use that? Well, because it’s too complicated. No, the reason that web development is so complicated is not the development, it’s the web. So if you are trying to solve the problem that J random manufacturing engineer, sitting on a production line, wants to automate some testing systems, take a real world example. You don’t say, oh, poor baby. You shouldn’t have to learn to code. You say, let you write the five line for-loop, but is actually the logic you want, and then I will clear this other CRUD out of your way.

And so, Anvil is, I suppose, it is technically low-code in that you have to write less code to produce something with Anvil than you would if you were producing it with a traditional like five-tier web application. But what Anvil really is, is a development environment simple enough that five line for-loop is enough to make your application work. You could either say this is a sort of trying to take the code away from you. Or you could say, no, this is a development environment with a real programming language, and that’s why we chose Python because it has a really extensive ecosystem. It is the world’s favorite first language for learners. It’s a real programming language. You can pick it up and do something real. You just won’t have to deal with all this cruft of putting the logic that you have just written into a web application and deploying it. So Anvil is a sort of anti low-code, anti no-code tool. Anvil’s animating principle is that code is good. Code is the right way to express most of the problems we have when we want a computer to do something. And the trick is to make writing the program as complex as your problem, and no more.

If you can build your user interface with a drag-and-drop designer, rather than having to write code to generate code and another programming language, the third programming language embedded in it. I mean, HTML has JavaScript and CSS embedded in it. Nightmare. Instead of having to do that, no, that is not essential to expressing your logic, use the drag-and-drop designer. What happens when you click a button? Well, now that is essential to your logic. So when you double click a button in the Anvil designer, it pops up a text editor and you write the Python function that runs when that button gets clicked. Because now you’re expressing logic, you want some real code. So I would argue that Anvil is not a low-code system. It’s the web toolkit we really need. But the categories of the world might disagree. And so we’re in this interesting place of sometimes being lumped in with a movement with which I have fundamental philosophical disagreement.

[00:18:08] Domain Knowledge Coder

[00:18:08] Henry Suryawirawan: So I think this kind of problem, maybe last time it exists a solution, right? I think Google Web Toolkit, if you are familiar with that. But it didn’t go nowhere. What do you think now is the right time to introduce back this kind of a toolkit? And is it something that because technology has been growing so rapidly that people need to build more and more customized solutions, like application, web applications that people with the domain knowledge need to be able to write an application now?

[00:18:35] Meredydd Luff: So I think it’s always been true that people with the domain knowledge are really, really important. I think one of the biggest challenges indirectly created by the present web development landscape is that the most efficient way to build something that solves your problem is to have it done by somebody or some people who understand the problem directly themselves. This is why your classic formula for the Silicon Valley startup is a domain expert in some domain that is not yet helped by software who can code, who can build this thing.

What that means is the magic ingredient to unlock this value that is software eating the world is to have a deep understanding of the problem that needs to be solved, and the ability to make it happen in the same skull. Because if you have that, then you can do your iterative design process. Because you can build a thing. You can try and go, actually, no that doesn’t quite solve the problem that I wanted, and you could iterate within yourself. Whereas if you are doing the classic thing that happens when somebody with some domain knowledge contracts a programmer to build something, they specify something. Specifications are necessarily incomplete, it comes back, and it’s not quite the right thing. And the iteration is incredibly slow and incredibly expensive. So having a person who understands it, be able to build it is really important.

[00:19:54] Henry Suryawirawan: So basically, the idea of the problem is that why now this kind of low-code and no-code tools becoming more popular? Is there any particular reason?

[00:20:02] Meredydd Luff: I think it’s for a couple of reasons. One is that as it’s become more apparent to everybody, that software is how we get a lot of things done, there is more pressure. And more people have been burnt by the experience of, for example, hiring external consultants, or trying to get some software built when that knowledge isn’t in the same skull. I think that’s a fair part of it. I think Google Web Toolkit was just incredibly clunky. It was a shot of a good idea. I think the modern version of what Google Web Toolkit was, you can see a lot more in something like a Phoenix Lite, which is this kind of thin client-ish thing where you have this process running on the backend, and actually, it’s spitting out chunks of HTML and every browser event gets funneled back to the server running this monolithic, monolithic processes running on the server, so you get to pretend that you’re actually writing something more like a traditional web desktop application that happens to be being accessed remotely.

It’s a cool technology. I think it’s orthogonal to the question of empowering domain experts, though. Because the domain experts still had to understand really quite a lot to use something like Phoenix. Especially with something like Phoenix, you need to drive a lot of HTML and CSS. Even if the paradigm for it is a little bit different. So I think I’m genuinely astonished. It’s the real answer. I’m genuinely astonished that something like Anvil did not exist already. And as I said, we waited around for a fair amount of time for somebody else to get on with it before we finally did. I think that low-code, no-code stuff is having a moment. There was a big “learn to code” movement. There was a lot of coding education stuff. You had president Obama going to code boot camps and that sort of thing. In the UK, you have the introduction with Computing GCSE.

And then that sort of way kind of realized, oh we’ve produced a whole bunch of people who can produce a Python program for school projects. But then they can’t turn that into something big that works. And so, we’re going to have to fumble them down the traditional web development environment, and you can’t possibly ask an accountant to do that as part of their ordinary work. So I guess we’re back to no-code tools. I suspect there’s a part of that. There’s a certain amount of you asking me to explain fashion. Why are high collars in this year? You can draw some stories, you can draw the artistic lines. But also at a certain point, it’s just a group awareness of the problem. Again, I think that awareness is right. I have some fairly fundamental issues with the particular shape of solution that is low-code or no-code systems. But I think it is good that people are noticing that, frankly, the programming tools we have built are not fit for the purpose.

[00:22:37] Demand for Developers

[00:22:37] Henry Suryawirawan: It’s also interesting that a lot of developers, I see it sometimes in a public forum or something like that, where people think, oh, it seems very apparent that the low-code, no-code, even AI now gets introduced to some of this development environment. So something like Copilot, if you have heard it before. So a lot of developers are concerned that, okay, this kind of tool seems to be eating up a lot of our potential opportunity. Do you think that one day, the demand for the developers will be kind of like winding down because of the advancement of this low-code, no-code or even AI?

[00:23:10] Meredydd Luff: Again, you’re asking me to get a crystal ball, so allow me to do some appropriate muttering. It remains astonishing to me how much leverage just being able to build an application is. There’s a lot of writing out there, especially in the entrepreneurial space, about the amount of untapped demand in building even quite niche line of business systems for people. I think once it became possible to do things with software, the world acquired what seems to be a bottomless demand for doing it all with software. For the reasons I’ve described above, I don’t think that no-code or practical low-code systems to make a serious dent in that. There is an industrial revolution happening of some sort. But things are still shifting in the direction of doing things online with custom-built software. We are currently the only set of people who could make that happen. I think it is right for that set to expand. I think that additional tooling so that people who have not put their entire careers into learning to be developers can still get something off the ground is going to be part of the answer. And I think that expanding the set of people who can do what we do is going to be part of the answer. And I think frankly, those are both good things.

But the sheer leverage that you can write a fairly small piece of software, and unlock an enormous amount of value in the world, means there’s still a pretty bottomless demand for what we do as far out as I can forecast. I think that Copilot is currently in the state of being a gimmick. The code it produces is usually right. But because it’s usually, you end up with needing somebody who actually knows how to code, and who can read the code that is generated to check that actually does what you want it to. This is true in all forms of applying neural networks, because they’re black boxes. They’re often very inconsistent and when they fail, they fail in weird, unpredictable ways. I think it’s going to be awhile before we see a neural network driving a car. Because the consequences of getting that wrong are so huge. And in similar ways, it’s going to be awhile before we see a neural network actually writing code without being in dialogue with the human programmer. Because the ways in which it will get things wrong will be weird and unpredictable and require a skilled human to undo. Maybe I will be made a clown for saying this in a year or two, and we will in fact, acquire some way of making these things reliable enough to trust sight unseen. But I personally doubt it. I think developers are around for the long haul, I’m sure.

[00:25:42] Importance of Product Documentation

[00:25:42] Henry Suryawirawan: So, moving on to the next topic, whether it’s developers or somebody (else) who writes the code. Nevertheless, if you’re building something, a product or an open source project, you need to write a good product documentation. So, which is the next topic that we want to discuss. You seem to bring this topic in a few of the conference talk. In the first place, why do you think that product documentation matter?

[00:26:04] Meredydd Luff: I’m probably going to go stick my neck out and be possibly slightly heretical about this. Because the conference talk you’re referring to is specifically writing better developer documentation. I’m co-founder of Anvil. It’s a developer tool. Developer tools, when it comes to documentation, are a little bit different to most things. Most software, the ideal is that you’re not going to need a manual. Developer tool because they have such complex interfaces, and your interface is offered in a textual API, you’re going to need documentation. And so, the analogy I like to use is that most software is built like the user spends their time looking out of the window or at the dashboard, and the manual is half forgotten in the glove box. But if you’re building a developer tool, whether that is a library, you’re hoping somebody will npm or pip install and use, or an API that you want people to call, or develop a platform like Anvil, your user interface is your documentation. That’s what the developer is going to be staring at while they’re using it. They’re going to be looking at your docs and their code and that’s it.

And so I think people systematically under-invest in developer documentation. Because all the shiny demos, of course, don’t involve looking through the documentation to find out what you should be doing next, because they’re all on some happy path. But in practice, the actual use of your product involves a lot of staring at documentation. If you think about the life cycle of a developer finding and develop a product specifically. By product here, I include everything from a commercial platform to open source libraries. They need to discover that it exists to begin with. They need to decide that it’s actually useful. It actually solves that problem. They need to do this. They need to be able to work out what it is even, and your documentation kind of defines that. And then, of course, they need to do the classic forms of learning how to use it and solving the problems they will encounter along the way, and that’s what people usually think documentation about, but it’s actually right the way through the life cycle. Especially, especially, especially if it’s developer product.

A thing I like to say is documentation is content marketing. Because if you’re solving a real problem out there, then somewhere there is a developer punching into Google. The question, how do I do exactly what your project does? Your documentation is literally the answer to that question. And so they should be finding it. Once they found it, I’ve already said it defines your product because someone lands on your homepage. The process of working out what it actually do, is often very woody or homepages often full of marketing focused. “Improve your productivity”. Yes. I know. I want to improve my productivity. What does it actually do? What do they want to click on? They click on the docs tab. If your docs don’t summarize what your product is actually about, you’re going to have a rough time getting anybody interested. So I think that developer focused companies. A developer focused projects in general of which companies are a subset that happens to contain me, systematically under invest in their documentation. It’s really interesting because you periodically get hints about this. You know, when Stripe documentation first came out, people were wowed by how easy it was to do. And yet, you still end up with developer focused APIs with the most perfunctory documentation. It’s perfunctory reference documentation. They haven’t even talked about examples or tutorials or how-tos because that always feels like an afterthought.

[00:29:16] Documentation Is Content Marketing

[00:29:16] Henry Suryawirawan: I think you bring one good point here is that the documentation, developer tools documentation, serves as a good content marketing. You mentioned a use case in which someone wants to solve a problem. They start from Google, right? And then if you have a good SEO, maybe about your product, your products should rank at the top probably search results. So I agree sometimes it’s under-invested, especially for a lot of developers who build the product. They just seem to think, if the product works, it solves the problem that they want, people should use it, right? So you build it and people will come and use it. I think in most cases, this certainly is not true. What will be your tips for people to start looking at the documentation as a content marketing tool?

[00:29:56] Meredydd Luff: So I think this is a worthwhile moment to mention that there are many different thoughts of documentation. Some of them are going to be more SEO fodder than others. There’s a really useful framework, actually. Daniele Procida, who is a really interesting chap, actually has given a bunch of talks at various conferences around this. Diataxis, DIATAXIS.fr is the current website of this framework, and he divides a documentation into four categories. You’ve got tutorials. So the step-by-step guides to learning how to use something. The how-to guide, which are step-by-step guides to accomplishing a particular practical task. The explanations, which is how and why does it work the way it does. And then the reference documentation, which is comprehensive and says everything about the machinery and how to operate it.

I have some small disagreements with him. I think it’s useful to separate the difference between API documentation. What functions are they? What arguments do they take? What’s this particular thing do? And reference documentation, which tells a little bit more of a story, A causes B causes C or A then B then C. If you are writing a unit test library, then you’ll have setup code, you’ll have test code, you’ll have tear down code. You need to talk about how those three things work together. You can’t just document the setup functions, the test functions or the tear down functions separately in the API documentation, and hope somebody will understand. But the framework, broadly, I think is pretty applicable.

So you have things like tutorials and explanations, that are the sort of discursive general education. Then you have things like how-to reference, which are actually usable when someone is trying to get something done. And then you’ve got these step-by-step tutorials and how-tos and the more theoretical explanations and references and API docs. All of these, if you’re looking at SEO and content marketing, how-to guides are the most SEO of all there, because they are the things that somebody is actively trying to do. And so, if you are looking to make yourself more discoverable then finding a bunch of classic use cases, and writing how-to guides, or “how to do X with your product”, then you’re onto a rich seam of Google queries.

But even without that, I do think that documentations are broadly construed. Things like conference talk where you’re talking about how to do a thing. You’re giving me tutorials, like these are always catching people’s attention. And you’re showing people how to do a thing, which is a very powerful way of getting the attention of a programmer. Because we tend to be tinkerers. We tend to want to pick something up and think, “Oh, that’s cool!” And so, if you flick something interesting across our field of vision, we’re likely to pick up the shiny thing and have a play with it. And if you’re lucky, we will remember it.

And then next time we have that problem, we go, “Oh, wait!” I know. Twilio is excellent at this. They give a famously rollicking demo in which they start up some node.js server somewhere. You start with receiving text messages and then replying to text messages, and then just write one for-loop, and everybody in the audience’s phone rings at once. That is clearly trivial, and it’s given to audiences anywhere and everywhere who might not, at that moment, have a need to integrate telephony into their application, but you’ve dangled it in front of them. That is also marketing because you’ve shown them how to do a cool thing. You’ve actually given them a mini tutorial. There’s a lot of tasks that we traditionally think of as documentation that matter much, much closer to the start of the funnel than we, as developers, typically think. We think of them as problem-solving tools and they are so much more than that.

[00:33:18] Online Q&A Forums

[00:33:18] Henry Suryawirawan: Thinking about early in the start of the funnel, right? So we mentioned about Google. So maybe Search Engine Optimization, SEO, is one thing. And these days, I think another source of funnel will be the online forums, things like Stack Overflow, or maybe some kind of forums where you ask questions and people answer. So I think this probably is also one of a good channel where you can actually put in your documentations. What is your view about this?

[00:33:43] Meredydd Luff: This is interesting. I don’t really think of a Q&A forum like that as a marketing channel so much. I think by the time somebody is searching Stack Overflow for the particular problem they’re having with your project, they’re already using your project. I think Q&A forums have a much more powerful role. They are used a bit in things like evaluating frameworks. If I’m looking into a new tool, I might check whatever that Q&A venue it happens to be. So people use Stack Overflow for this a lot. Anvil runs our own forum. We use Discourse. It’s open source. It’s free. It’s great. So we self hosted our own website, which I kind of recommend if you can, because Stack Overflow is famously a bit arbitrary and has a very strong set of norms, and you might not want your user community to be shaped by those norms. And yes, if you’re evaluating a new framework, you might stick your head into their Q&A forum. Some people even use things like Slack channels and Discord, which I really don’t think is a good idea.

Because what I think is the biggest advantage of Q&A forums is that they are a user generated set of bug reports against your documentation. Anybody who is asking a question in your Q&A environment is stuck on something. That probably means that your documentation hasn’t pointed them in the right place. Even better than that, whether it is provided by community members or by developers themselves of the underlying project, the answer in the Q&A forum is a patch against that documentation. Because what it means is that people can search the error message they’re seeing, and they will see an authoritative answer, even if the documentation doesn’t actually answer that question yet.

But that only works if you do it in a publicly searchable space, if you do it somewhere like Stack Overflow, you do it somewhere like a forum that is browsable by anonymous users. And so, if you just do that in a Discord or Slack channel, you get the bug reports as a developer. You find out what people are asking questions about. And don’t get me wrong, that’s really valuable. But then your answers disappear into the ether. They’re not searchable. They’re behind some kind of wall and they scroll away into the never, never. Whereas if you use a publicly visible and searchable Q&A environment, it forms almost a sixth pillar of your documentation. You’ve got your examples. You’ve got your tutorials. You’ve got your how-tos. You’ve got your reference. You’ve got your API documentation. And then you’ve got the Q&A, which is the sort of self-healing catch-all, where the holes in your documentation get plugged, because those are the things that people want to ask questions about, and so those are the things that get answered, whether by the community or by the team maintaining the project. Your documentation becomes self healing. If you’re using an environment like Stack Overflow or Discourse, you can have upvotes and favorites to say, “Hey, these are the bug reports that are really important and the patches need to go upstream, and documentation.” People always ask about this. So it should be covered more prominently in your documentation.

These are all the benefits you get from having your Q&A in a little bit more traditional web environment. Yeah, don’t use Slack. Don’t use Discord. Do use Discourse, annoyingly similar names, or Stack Overflow or something else. But yes, absolutely. Having a Q&A forum is vitally important. It provides not just a signal to your potential users that your community is alive and kicking. But it makes your documentation self-healing, and it allows people to report bugs and patches against your own documentation.

[00:36:55] Developer Advocates

[00:36:55] Henry Suryawirawan: Yeah. I like the way that you mentioned the usage of these Q&A tools like Stack Overflow. So people who ask questions there, basically, it’s the analogy of submitting bug reports, right? And I think if your product is popular enough, you will get a lot of such questions. And probably from there, you can also see if good answers, those that are upvoted probably, is like a patch to your documentation. You probably have to look at all these answers, and maybe improve your documentation, which I think some of the companies do have dedicated full-time employee doing that. Like managing the discussion or some kind of hashtag in the forum so that they can actually watch what people are asking. And at the same time, if there are chances to improve their product documentation, they will do so as well, or even improving the product features itself.

[00:37:42] Meredydd Luff: Yes, If you are a developer in a developer focused company, that person’s job title is likely to be developer advocate. Unsurprisingly, we have quite a few of those on our team, and we do exactly that. But it is quite important. It is possible to have something like a community manager who’s just making sure things are flowing, making sure questions get answered, but really, you want the people doing this to be programmers, to be software developers who can actually answer questions, provide authoritative answers. Not just recognize that a question is getting answered, but make sure a question is getting answered well.

This is an internal leadership question. You need to give them the authority, the loud enough voice to speak on behalf of your users, as well as on behalf of you to your users. It’s one of the reasons the community likes the term developer advocate. Like, the advocacy goes both ways. But basically, you should be listening to them. They should be important people in your team. They should be people important enough to sort of grab the dev team by the ears and swivel their heads and force them to look at a problem that people are experiencing. Because developers love not looking at problems. And so, the trick is to make sure that people are actually in contact with the people who are having the problems. The closer you can get that process to the developer team, the better.

Actually, I mean, I say developer advocates do this for the Anvil forums. We actually have a regular rotation of who is watching the forum. The platform developers who are working on the Anvil product are absolutely on that team as well. It’s like the old adage. Everybody should do support at least sometimes. And you have these stories, good ones, of CEOs of big companies sitting down and doing it, phoneship support shift, because that rubs their nose in what are the problems that users are actually having, rather than the ones we theorized in the last meeting.

[00:39:25] Henry Suryawirawan: That’s actually also a good point because sometimes, we do have on-call rotation for incidents. When something’s wrong with your backend or your products, we do have on-call rotation. But I think you bring another good point. On-call rotation for looking at the forum or Q&A tool, so that people get empathy with the users who are actually using your product as a developer.

[00:39:43] 3 Tech Lead Wisdom

[00:39:43] Henry Suryawirawan: So, thanks again for all this exciting talk, Meredydd. Unfortunately, we reached the end of our conversation. But before I let you go, normally I have this one last question that I always ask for all my guests, which is to share your three technical leadership wisdom. This is something that maybe you want to share with all the listeners, maybe based on your career, maybe based on your experience. What will be the three technical leadership wisdom?

[00:40:05] Meredydd Luff: Okay. Three pieces of technical leadership wisdom. I want to start out by saying that what I say here, I think I will say with lower confidence than most other things I’ve said here. Because I still consider myself more professional as a developer than professional as a manager. I think the first thing I would say is to lead by example. If you are doing the classic Tech Lead role, you are on the border of technical to managerial. You’re coming from the technical side. Then you lead by example. That technical competence will earn you trust for the other things that you want to do. If you want to make a change, then this is really handy to have built trust with technical competence. That’s not the only way to build trust. I’m sure other people have other routes in being a really good manager can build confidence in you when you are making a change that has technical implications.

I have already said that my background is not professional manager. My background is technology. And anyway, we’re just a startup. We are necessarily making all of this stuff up as we go along. I’ve described our management style as brute force and empathy, which is to say, the most important part you can get away with not knowing what you are doing is if you are just very human about it. So far, this has worked really well for us. The most important thing is these people are people, and if you would like to understand what is going on in their heads and to have them happy or satisfied as well as going in the direction that you want to do. I think that we have found so far, touch wood, is that you can not have a lot of management theory. But if you have the empathy to be looking inside your colleagues' heads, and caring about how they are feeling, that will get you an awful long way if you’re making that transition.

To lead by example, brute force and empathy. Final thing is a little bit more on the management side, which is give junior people a chance. I think a lot of people are chasing their white whales of that super senior developer who has 10 years experience doing exactly what they want. This is apart from anything else. This is going to be a very competitive place to hire because you are trying to hire where all the people with the biggest pockets are trying to hire. By the time they’d built that much experience, they know what they want and they could have take an awful lot of wooing, and have probably already found somewhere they’re already quite happy. We had great results from investing in junior people.

So the first developer that Anvil ever hired was nine months out of a boot camp, but just phenomenally clever and really knew what she was doing. By allowing ourselves to be interested in people like that. Not saying, oh, well, she doesn’t have 10 years of experience. Then we allowed ourselves to hire somebody really great, of who other people may have overlooked. The second developer we hired had never worked as a developer before we hired him. In his previous job, he’s a maths teacher. But he’d been participating in our forums. He had demonstrated his skills, but didn’t have a full background. Doesn’t matter. The craft of software engineering, which is in large part cooperation and working together. That’s the thing that you can learn from example from a functional team. But talent like that, finding what you can, and don’t overlook the junior folks just because the CV doesn’t have the right number of lines of code in. There are far too many examples of founders of large companies putting anonymized versions of their CV from back when they started their company through their recruitment process and not even getting an interview. There should be much sooner to discovering a problem like that. You should have a mental thing in the back of your head that any hiring process that would not hire «insert name here» is broken. Any hiring process that wouldn’t have hired Bridget is broken.

[00:43:38] Henry Suryawirawan: Thanks for sharing all this interesting wisdom. I like all of them, actually. Brute force and empathy is something that is really important as well, in my opinion, because yeah, sometimes we’re just making it up, especially if you’re working in a startup. I think the key thing, everyone is a human and so treat them well as a human as well.

Thanks again, Meredydd for your time. So for people who are interested to know more about you, or maybe trying out Anvil, where they can find you online?

[00:44:02] Meredydd Luff: So you can find us at Anvil.Works where, of course, it is free to use. The application builder, just hit start building up in the top right corner. You can use the application builder, you can deploy your own applications. If you are interested in what I’ve been talking about with documentation, we, of course, have tons of tutorials and examples for you to play around with. Or you can join us on our community forum, and see what I’m saying about our developer advocacy. If you want to follow me, I am @Meredydd on Twitter, which is M-E-R-E-D-Y-D-D. You might want to find my by the Anvil account. But it has been really great talking to you. Thank you very much for having me on.

[00:44:39] Henry Suryawirawan: Likewise here. So good luck with all the Anvil journey. I wish you good luck.

[00:44:43] Meredydd Luff: Thank you very much. All right. Bye bye then.

– End –