Documentation for developers – WPCampus 2018 – WordPress in Higher Education

Documentation for developers – WPCampus 2018 – WordPress in Higher Education

September 2, 2019 0 By Ronny Jaskolski


– [Katherine] Good afternoon, folks. – [Audience] Afternoon. – [Katherine] Last session of the day. I’m sure your brains are as full as mine, but thank you for making time for this. As we get started on the
topic of documentation, just to level set up front. How many folks in the room
are actually developers who are looking to improve
documentation skills? Oh, awesome, most of the room, fantastic! How many of you are project owners trying to make your
developers write documentation? (audience laughing) All right (laughing). Excellent, okay. Well, we’re gonna try to make
it as simple as possible, so part of what we’re
gonna talk about today are tips and tricks on both
sides of that great divide. Things we’re gonna talk about today. Just to give you a little
bit more background on me up front. As they said, my name’s Katherine White. I am the Director of
Engineering at Kanopi Studios. We are a digital development agency. We specialize in WordPress
and Drupal development, and I do a lot of work with clients in higher education and non-profit, and as well in small business. And at Kanopi, one thing we do is we’re split about 50-50 between working with our clients
on rebuilds of their sites or new builds of their sites, and about 50% of our business is in where folks with
pre-existing WordPress sites or pre-existing Drupal sites come into my organization
desperate for help. And that is honestly where my passion for this particular topic was born, because documentation, and
documentation of your code base and your project become so critical to the life of your project. And as code passes hands, making sure that people are able to be as efficient as possible and move your project forward in a way in which you intended. So we’re gonna talk
about a bunch of things in the next 40 minutes. We’re gonna talk about
why documentation matters. This is one of those
things as developers we’re constantly asked to do. Why is it important? Who are our audiences that
we’re writing for, typically, within our organizations? When we talk about
documentation there can, sometimes there’s nothing as terrifying as that blank page. So what are the kinds of
things that we need to include in our documentation, for it to be substantive and helpful? Schools that we can use
and tips that we can use for writing those documents. And then we’re gonna talk
about how to keep it fresh over the course of your project lifecycle. And, finally, how do we make this happen? How do we build this into our process as something that we’re
constantly thinking about? So why does it matter? Everybody’s always asking
you for documentation. Why is it important? Why do they care? Why should you care? It really boils down to what I consider to be three main areas. The maintainability of your code, the community that you’re trying
to build around your code, and then there’s a personal
development component to this as well. The number one reason I ask developers to write documentation, is that especially in an
institution, in higher education, we’ll be using this code a year from now. You’re building for the long game, we are doing projects that need to last, needs to withstand the test
of time and be extensible. But the reality is as a developer, that new cute, kitschy trick you learned, that you know and then
build into your code, you come back to that
code six months from now, and it’s going to look like
it was built by a stranger. A mad genius. I cannot tell you the number
of time that I, myself, have looked at plugins I’ve written a year or so ago, and I go, “Wow, I was really smart!” I don’t know what I was doing, and I can’t redo now, but I was completely brilliant
at that point in time. The more you look at it, and you’re just horribly embarrassed, and you think about how much
you’ve grown since then, and how horribly inefficient this is. But the reality is, you wouldn’t recognize
it at your own code. The flip side of that
is that somebody else may be using your code in a year. So, I found an interesting statistic in the stack overflow developer surveys that they do every year, that almost 35% of developers
cite poor documentation as one of their primary
frustrations at work. It’s right behind
unrealistic expectations, which of course we’re all
very, very familiar with. So, don’t be this person (laughing). Don’t be this person that
causes 35% of our colleagues pain and suffering at work. Even if you are no longer
maintaining a code, somebody else will be. From an adoption and community standpoint. There’s nothing more frustrating than building code that people don’t use. One of the challenge we
face in higher education as you’ve probably heard for basically throughout the conference here, is this decentralization
problem that we all deal with with our websites. You can expend a great deal of effort on a one-system solution, only to have random research
groups and departments not adopt it. If you want them to use it, you have to make it easy to figure out. You’ve got to make it clear
what the solution is for, why they should use it, why they should be a
part of this community that we’re trying to build. To encourage their participation, they’ve gotta understand the value of what you’re putting out there, and you’ve gotta make it easy
for them to be a part of it. As a individual developer, from a personal development standpoint, documentation is actually critical if you want to write
stronger and better code. The best way to make sure that you understand what you’re doing, is to have to explain it to somebody else. This is where conversation
with your peers, bouncing things around, talking about your
architectural decisions, you being to see holes in
what you’re doing, right? Documentation is another way to do that. Sometimes I will actually
start, more or less, with the documentation, and describing what it
is I’m about to build. Because I’ll begin to see the holes in it before I’ve even really gotten started. And candidly, there’s a
vulnerability component to this. Developers who can actually
be articulate in writing are extraordinarily rare. Working on your writing skills, practicing your writing skills, being able to present technical concepts to less technical audiences. All of these make you a
more valuable employee, and a more valuable developer. And the more that you write, the more that you practice this, the easier it will become
to do it over time. So, who are the people, and as developers, we’re
actually writing for. And we’re talking about writing in the context of this discussion, this is not a talk about PHP Doc, okay? This is a conversation about
higher level documentation, about what your project actually does, why it does it, and who it’s for. So in the who it’s for department, who are the people that we’re talking to? The people who influence the
documentation at the ready. First we’ve got stakeholders. And I’ve done these as rough personas. And sometimes as developers, I think we feel like we’re so far removed
from the stakeholders, stuff that we do in our
day to day doesn’t matter. But that’s actually not true. Your stakeholders may be technical. Your stakeholders may be central IT. One thing you can be sure of is that they understand
the business requirements. Why did you set out on the
path to doing this site, doing this project? What the organization
impact of that project is and why do they care about it? They help fund our work. And, when we talk about
the adoption component, building that community, they help to drive that from the top down, or they can kill your project dead. So making sure that the
documentation you provide gives them the high level
context to understand its benefit is actually critical. Implementers in our context, could be developers, but
they aren’t necessarily. People who are implementing have a problem that they need to solve. They may have varying levels
of technical facility. This may be a student webmaster who’s helping out with something, this may be an IT professional. Inevitably, especially
in higher education, they’re gonna be strapped
for time and resources. So making sure that the project is easy to pick up on quickly and implement and use is critical. They want to interact
with your functionality but not necessarily with your code. And if you are fortunate enough to be working in an institution where you have the opportunity to open source some of your work, this may or may not be somebody who’s internal to your organization. The final audience, and of course what we want to talk about, are out developers. That’s the people who are in the weeds. The folks who are adapting and extending, building on your code. From outside your organization, these could be potentially
people who are interested in being a part of your project, they want to contribute back
to the open source community. What you’ve done has
attracted their attention, they want to build on it and adapt. These can be your technical teammates. Or these can be people you don’t even know who are going to be supporting
this work long-term. Even if the project gets
handed off down the road. So those are a lot of different audiences with a lot of conflicting needs. So what do we need to include when we’re writing documentation for them? We’re going to speak specifically here about documentation quality
as it pertains to plugins that you’re producing. So when we talk about a
good, high quality plugin, we talk about high quality code. There’s a documentation
component to that as well. So, when we are writing up
information on our project for the community at large, stuff that applies to pretty much anybody who might be looking at this plugin. There are some fundamentals that you want to make sure you address. Number one, what’s the
problem you’re solving. Nobody’s gonna use a plugin if they don’t understand what it’s for. How does this solve my problem? Give a basic example
of how the thing works. If you have a really
common use case though, don’t be cute and fun with it. Make it simple, make it approachable, definition of how the most
common use case for the thing. And then beyond that, what are the major features that your functionality provides? The next step is how do
you install this thing? And I can’t emphasize enough here, make no assumptions! Make no assumptions about they way someone’s
system is configured, about the way someone’s
site is configured. When it comes to installing the code if there are dependencies, people need to know that upfront, which is also part of
what is it built with? Are there tools that you’re using? Are there versions that matter? Proving that information so that people set them up for success, so that people out of the gate are able to get your project running the way that you intended to create. Where can you get help? It is so important, especially if you are open
sourcing your project, that people can get in touch with a queue. That can be your issue queue, that can be a slack channel, that can be a lot of different things, depending on what works for
you and your organization, but make sure that there’s way that they can ultimately have
a conversation with somebody if they’re having trouble. When can you use it? So, with any plugin that we write, there’s a licensing considerations of when it’s okay to use this plugin, what is the license
that’s associated with it? How am I able to adapt
and build and modify on this piece of code? And then finally, let people know what’s changed. If you’ve got code that’s
been in the wild for a while, you may have people using
really old versions of it. Make sure that you’re being clear about new features and functionality, or stuff that you’re no longer supporting, or things that may have changed, before they hit that upgrade button, so that they don’t break their whole site. Then there are the folks that actually want to be in the code. And this can vary based on whether you are
inside an organization, I might tell you to include
slightly different things than if it’s in an open source context. But, how do you set up a local? So again, if you’re gonna build
a local develop environment to work on this code, what does that look like? Again, make no assumptions about
what people have installed. How is the project architect? This is an opportunity
to unload your crazy. If there are weird things in the code, let people know that upfront. Let them know where to find
certain types of things, if they may be looking for a specific aspect
or feature of your code. For contribution, define
the rules of the road. There’s no feeling that hurts more than trying, you get out there
and be a part of something, and issue a PR and you’re rejected! So, again, set developers up for success, by letting them know what
your expectation are up front, about what testing process
the code has been through, what they’re expected to
provide for the issue of PR, that kind of thing. And then finally, this is important from a
more internal perspective, if you have deployment guidelines that people need to follow, or if they are just (mumbling) just like, “Hey, when you deploy this code, “make sure you clear the cache.” That kind of thing. Go ahead and note those here as well. ‘Cause this is really the
care and feeding of the code from a developer perspective. There’s a lot of
information to write about. Especially if your loop
is not lit too bright. So, what kind of systems
are there out there for actually writing our docs? Up front I’m gonna say this
doesn’t have to be hard. But I do want to say that
your writing does matter. So, complete sentences matter. Approachability matters. Structure of your documentation matters. Avoid getting overly technical. Don’t give complicated
when simple will do. Be approachable. If there are third party tools
or supporting documentation, that helps people understand
the scope of your project, link those in. If you are using a lot of
acronyms, technical terms, link those in as well. This may be a really senior developer looking at your project
who knows all this stuff, it may be somebody who’s
just getting started. So help them understand
what these things are. One thing I like to do when
I’m writing documentation is think in stories. Now, if you work in an environment where you’re following an agile workflow, user stories may be a
really familiar concept. If you’re not, then it may be something new. But as developer I actually
find them to be a great tool for helping me simplify my explanation as to what I am building
and why I am building it. So, user stories follow this format of, as a person, I should
be able to do a thing for a reason. And taking that concept can
really help you mentally figure out how to articulate what your little piece of
the WordPress flow does, and why it does it. Documentation is useless
if it’s not up to date. So, be consistent with your project. Update your documentation
as you plan, as you build. Getting into this habit, my developers have come
back and confessed to me that once they develop this habit, so much less painful. Because they don’t have to go back and the very, very end of the project and start writing this. Just like if you build all
your docblocks as you go, you don’t have to go
back and painstakingly add all of your functional documentation after you already built the thing. Don’t scope creep yourself. So, what I mean here is once you get on a roll with this, it can become really easy to just throw the kitchen sink at it and document everything
you can possibly think of. Part of the reason I
recommend this approach to managing your documentation, is because nobody likes v-spec documents. So as much as possible, break up your documentation so that it lives at the
deepest possible level. So by that I mean, if you look at, say, the Gutenberg plugin. The way they structured
their documentation. As you drill deeper through the plugin, you get different levels of information. It’s a really nice structure that makes what you’re reading bite-sized. Also also, more maintainable. I also encourage developers
to do what we know. We live and breathe in text editors. Plain text is our happy place. So document that way. Use simple, text-based
formats to document your code. Don’t make it hard. I usually recommend Markdown. There are a lot of other
plain text formats, this just happens to be what I use. And that’s largely because I
do all of my work in GitHub. So, that’s gonna be the bias
in this particular section. In terms of how to structure
these documents, right? So, okay, we’re gonna
work with Markdown, cool. Where do we start? We start with a README. This is your really, really basic organ. And we’re talking about
this in the concept of it in the context of a plugin, but I also encourage
READMEs at theme level, at your overall project level. It’s kind of the welcome
page for your functionality. So this is where a lot of
the high level review stuff that we talked about should go. If you’ve got no other
piece of documentation in your repository, have this one. We touched on this briefly already, but have a license file. If you’re working with WordPress, then you’re gonna wanna do something that is compatible with
GPL version 2 or higher. Choosalicense.com is a great tool, just asks use and language questions to help you find the right license for what it is that you’re doing. The third file in importance
from my perspective, if you’re gonna have one, is a contribute file. This goes back to those rules
of the road we talked about. So your contribution content is patching, code review practices, development-specific criteria. Stuff you’re gonna be looking for when some of the issues (mumbling) is trying to submit code to your projects. Getting started as a writer
can be really intimidating if writing is not your thing. So I did want to also
include some resources here that can help with the
structure and content of your handle of the documentation. So Grammarly is a writing assistant, if you don’t use it I highly encourage it, especially if you use
web mail clients a lot. This is a free plugin
that will correct grammar, it will correct your spelling, it will look at your sentence structure and make recommendations. So it can really help with
the quality of your writing. Readable.io is another great tool that does the same types of things, it’ll look for passive voice, it’ll give you the reading
level of your content, which from an accessibility
standpoint, matters. The lower you can make the grade level of the content that you’re writing, the more it’s going to
be accessible to people. And the Hemmingway Editor is another tool that does similar things. So, in terms of boning up
on your writing skills, those are great tools to know about. If you, by the way, I see
you folks taking pictures. If you want to download these slides, I do have the link in the deck and it will be posted on the site. But if you download them all, these are the links that
you can access materials on. And then I also included
just a couple of things for use with Markdown. If Markdown’s really unfamiliar, StackEdit’s a good place to start, because it gives you a kind
of side by side comparison of here I am I need it in Markdown, and here’s what it actually
looks like in HTML. Cool, okay. And then just a couple of
other cheat sheets there to help get you started with that. So, once we’ve built all
this beautiful documentation, that’s neat, how do we keep it fresh? Well, we need to have a canonical source, because just like
decentralized sites are painful for us to maintain, decentralized documentation also hurts. Relying on things that
live over here in Jira, and things that live over
here in the code base, and things that live somewhere else, is a little bit painful. So, I like to try to
make one canonical source that references everything
as much as possible. Again, be reasonable here, because, don’t, you know,
this is not an open doc. But, it’s good to track
our changes over time. So when we keep documentation
in our version control system like we’re talking about
with Markdown files in your code base, you get a picture as your
code environments evolve of where you’ve been
and where you’re going. That’s if you’re not
doing version control, it’s a much more important
conversation than this one, so we can chat afterwards. But, track your changes over time as a part of your code base, it’s basically the freebie that you get with doing this stuff, doing things this way. Keeping it with that code. It’s also the only place that I know developers will actually look at it. Maybe your organization is
different from mine (laughing). But what I have found is if
it travels with the code base, which is the only thing that’s going to exist
for the life of the code, then nobody has an excuse
not to have seen it. And I recommend if you’re
using version control and using it in WorkFlow, leverage your pull requests as an opportunity to provide
further documentation about key points in the
evolution of your project. So, I recommend and what we do at Kanopi is we use a template for this, to add some structure to it, then make sure that people are providing before and after screenshots, URLs are perfected, any
addition information, dependencies are added as a part of this pull request, et cetera. So, your pull requests can represent these key intersections and points of inclusion of functionality of your site. They can provide little more detail, but then don’t require anybody to dig back into a granular (microphone
banging obstructing speech). Same thing with release notes. So we’ve talked a little bit
about keeping your change log. This is also a good place to
articulate that information with your tactical teams, making sure that you’re being
clear on what’s been added, what’s changed. One interesting thing we’ve started to do is actually build our project
requirements in Markdown. And keep them in a docs folder that lives as part of the site. So you can use this model
to extend documentation off to that stakeholder model. So it can support our full
requirements documentation and have that live with the site, along with the user manual,
along with the code. So that everything is packaged together. When we take that approach, I then recommend, and even
just for your README file, generating a static site. For if you use GitHub, for example, you can produce your documentation, and very, very easily publish
something out to GitHub Pages to get your site up online. Your documentation is more easily browsed than it is inside of your repository. The tools I mentioned here, MkDocs is what we use, but Couscous is another PHP based tool. These create HTML documentation sites that’ll take a big
collection of Markdown files and give you a beautiful site output. We take this approach
because Markdown on its own does have limitations
if you’re gonna start getting into the complex
documentation structures. Because it’s harder to
have a table of contents, it’s harder to be able to
structure the information. So this helps you get around
some of those limitations. And I mentioned GitHub Pages, but there are other option
if you’re not using GitHub. The hosts like Read the Docs or Netlify, I think I say that right, I’m not positive. But they make it very easy
and in any case it’s free to create static documentation
sites for your projects. That sounds awesome! If we all know what’s going
on, it would be incredible! How can we make that happen? How do we build this into everyday life? Our solution has been, my solution has been, to make it a part of our workflow. So, we actually will reject
pull requests within my agency, if the documentation is not included as part of the pull request. Drives everybody crazy, but it means that I get docs as we go. So that consistency is key. And again, you know, trying to bring it down
to the micro level, as opposed to just the macro level; to make it a little bit easier, a little less painful,
a little less daunting. We’ll do it on a pull request
by pull request basis, and make those subjects (mumbling). The other thing I wanna say
with regards to making it happen is that something is better than nothing, as long as it’s accurate (laughing). So, start small. Again, just have a README. And even if your README is not the most beautifully complex
and complete thing it could be, it’s a start. So don’t, I would caution against, not starting down this road because you don’t have
a full-fledged plan. Incremental improvement is a thing. To that end, the best is the enemy of the good. So, as a writer, as an aspiring fiction writer, first draft’s always terrible, right? But it’s a draft. So, just get it written, and then go back and polish, make it better, get feedback on it. People will have questions, you’ll have issues come in. It gives you more information
to add to your project to help other people who might
run into that same issue. So, don’t be afraid to get started, just because it’s not perfect. That’s it. So, are there questions,
feedback, thoughts? I have the link up there
for feedback on the session, and of course you’re welcome
to hit me up on Twitter after this. But I wanted to get lot
of questions up front. Sure (laughing)! – [Male] Do you have
an example of a Boolean or open source product that you found the
documentation being excellent, or did exceed your expectations? – [Katherine] Ooh, that’s
a really good question. I know we actually, it’s gonna sound silly, but I did mention it, and I know that everything
is still very much in flux, but I have been really impressed
with the level of effort that’s gone into Gutenberg documentation. Regardless of how you
feel about Gutenberg. They’re doing, I think
a stellar job at this. Also, linked in the deck
I’ve got some examples of pull request templates
that I think are really nice and full featured. What are some other plugins
that I’m really impressed with their plugin level documentation? I’ll have to think on that. That’s the one that
jumps out at me upfront, and maybe that’s just because
(mumbling) spend time with me. Yeah? – [Male 2] You mentioned a
central source of documentation to help keep it from
being too decentralized. Is that something to implement currently, how do we do it? Any suggestions? I’m thinking like, there
isn’t some place like a wiki, for not in code documentation, stuff you can code in, without being redundant adding… – [Kathrine] So that’s
an interesting question. So the question was, this canonical source of documentation, have we achieved it, where does it live? Wikis versus code level documentation. And it’s actually a
debate that I had a lot getting started down this road, was do I want to keep more
user-facing documentation in my code base, or do I wanna leverage the wiki feature that’s available to me as
part of my version info system to present that information? For better or for worse, I have chosen to go the
route of keep it in the code and publish on the unfound pages, as opposed to really
leveraging the wiki feature. That being said, this is mostly stuff I’m
building for clients, and it’s not stuff that is really contributing back to the community. I think user level
documentation in the wiki, in that context, makes more sense. But what I am doing right now in terms of the canonical
source of documentation, is using the code base. So what we’re doing right now, and it’s been an interesting experiment, and we’ve done several clients and we’re continuing to iterate on it, is produce one of these
documentation websites that we use for our
requirements discussions with our stakeholders. And that contains all the user stories and all that information, that then gets pulled out of the Markdown and magically set-up to
become tasks in our system. We’ll also keep links with
all of our epics and things to the appropriate version of Wireframes, to the appropriate version
of our content diagram, whatever it is. So that while those artifacts
are actually centralized, we have one place where developers go to know everything they need
to know to build the thing. So it may not be truly the
single source of truth, because we have these other documents for better serves by better applications, but they know there’s one place to go to know exactly what version
of what initiative we have. Yeah? – [Male 3] Would you
do anything differently or change anything for a
systems level documentation? So like, bringing on a new developer and they have to learn
about your server structure, or things like that, so that they can start working
in your code environment? – [Katherine] That’s a good question. So the question was system
level documentation, and we really focused on plugin level. But the reality is to your point, there are all sorts of different levels of documentation, right? And, I feel like this code based approach has pretty specific uses. So in terms of systems
level documentation, I wouldn’t approach that this way. – [Male 3] Okay. – [Katherine] That said, what we’ve tended to do is
certain components of it. You can live that way, but we have kind of larger, and I actually use a wiki for this, that’s internal, that point to various projects. So, for example, when it comes to our employment process or our continuous integration process, well, those files actually live in a repo that’s got its own documentation. But I have an external source that pulls all the pieces together to give people a larger
scale view of the system. – [Male 3] Thanks. – [Kathrine] Yup. And it is one thing that, when we are building a lot of
custom plugins for a project, it goes back to that
dependency discussion. Of understanding how
these pieces work together to create the system, is something I’m trying to articulate as a part of the documentation
of the individual components. This is the role that this
component plays for this site. So again, that’s more of
an internal facing style, as opposed to something that’s designed, and the code may be designed
with the ultimate intent to contribute back. But the documentation was
designed for it to exist in a single context. Any other questions? Yeah? – [Male 4] When you deny a pull request, to ensure that the
documentation is included, do you find yourself having to
(mumbling) on the (mumbling) fixed a bunch of bugs
and some other stuff? Do you reject subjectively
based on the quality of it? – [Kathrine] It is a little subjective. And it’s an extreme question. So the question was, when we were doing documentation review as a part of PR review, what are the parameters that, what is the case in which
documentation will pass a PR, what’s the context in which it will fail? And it is subjective. When I am looking at that, there are certain, and again, I use a template
for this which kinda helps. So if I’m looking for
specific information on, not just, yeah, it’s a
bug and I fix the stuff, but here are steps to reproduce. So here was the original issue, here are the steps to reproduce so you can actually check the fix. Here are any dependencies
I’ve added to the code base to help handle this fix. So we’re looking for a
certain level of specificity. But very specifically what
I am actually looking for is a restatement of the
acceptance criteria, that were part of the reasons was, this was a thing to begin with, and then have my validating
against this criteria. Those are kind of my bare minimum things that I’m looking for. Good questions. All right. Guess we’re good. – [Male Student] Thank you. (class applauding) – [Male 5] Everyone please.