The Secret Sauce, Ep. 32: Documentation and Training

There are many benefits to documenting your project and teaching someone else how to use it.

Senior Engineer Ryan Price dives into the importance of documentation in this week’s episode of the Secret Sauce. 

iTunes | RSS Feed | Download| Transcript

Stay connected with the latest news on web strategy, design, and development.

Sign up for our newsletter.

Transcript

Allison Manley [AM]: Hello and welcome to The Secret Sauce, a short podcast by Palantir.net, that offers a little bit of advice to help your business run better. I’m Allison Manley, an Account Manager, and today we have Senior Engineer Ryan Price talking about the importance of documentation and training.  

Ryan Price [RP]: My name is Ryan Price, and I want to talk a little bit today about documentation and training. Probably the key person that I think about when I get into the role of writing documentation for a project is future me. Who is the person that will be reading this later, and who is the person that’s going to get the most benefit out of it? Then I sort of go from there, because the more people that get involved with the project — whether it’s someone on the client side, whether they’re technical or non-technical, whether it’s other members of the development team, or maybe my project manager — all of those people are going to read or edit or touch the documentation of a project at some point.

And on a lot of projects I’ve worked on in the past, I have been in the role of training the new people who are going to be using that project, whether it’s other developers or the content editor who’s working on the client side. And all of those people need to know what this website is supposed to be doing. Beyond just the business goals, there’s lots of nuts and bolts things, and in the land of Drupal we have lots of nuts and bolts things. And for some people those things are totally new, and they have fun new words like ‘nodes’ and ‘taxonomy’ and ‘views.’ And for other people, they know those things, but they haven’t seen this way for placing blocks in this context, whatever that happens to be.

So I think even a simple project that is just a brochure site would still have documentation that needs to be written for future me. When I come back to this project, I don’t want to spend five hours remembering my motivation behind making a new field for this. It should just be there. What does this field do and why do we have it? You want to get this stuff out of your head. If you get hit by a bus, you don’t want to be the person on the project who made something that was indecipherable and everyone needs to sit around and figure it out.

And the other thing is, when you explain something, you learn it. There’s doing it and being able to do it yourself, versus having to write it down. For me, translating something out of my head into speaking is when I really understand what it is that I’m doing, or writing it down at the same time. And you can also discover things about the project, too. Like discovering when a requirement is unclear, or when a piece of work is not quite polished. Because you’re getting ready to document it, and you say, it’s supposed to do these nine things and it does eight of them really well.

So there are lots and lots of benefits to documenting your project and teaching someone else how to use it, and I think probably the key person among those is future me. Thank you for listening!

AM: Thanks Ryan. That’s the end of this week’s Secret Sauce. For more great tips, please check out our website at Palantir.net. You can also follow us on twitter at @palantir. Have a great day!

Development Drupal Open Source