Sample apps
Sample apps aren’t just a convenience for developers, nor even an illuminating demonstration of abstract concepts in code. Sample apps are critical for technical writers to write good documentation. Without the ability to test content through a sample app, it’s nearly impossible to know if your code instructions in your docs work.
Whether a sample app is relevant and available depends on the nature of the product, but in general you need sample apps or sample code to make sure the steps in the documentation work correctly. Additionally, sample apps tend to be powerful learning tools for developers because they allow them to experiment and see code in context from end to end.
- Sample apps are critical to writing good docs
- Getting approval to publish sample apps
- Code simplicity versus more robust functionality
- Functional but poorly written code
- Who owns and maintains the sample app?
Sample apps are critical to writing good docs
Let me start the discussion by sharing an experience related to sample apps. At one company, I was working on documentation for a project called Video Skills for Fire TV Apps. This product involves implementing Alexa video skills into Fire TV apps so that customers can say phrases like “Play Bosch” and the app will automatically play the content, without the need to use a remote control.
The implementation process was pretty involved and required a series of steps listed here. I inherited an initial set of docs (written by a PM + engineers) and sample app. I spent a month just getting the steps to work with the sample app. Then I spent another month fixing and updating the documentation. Using a sample app was critical for determining which steps in the initial docs were missing or incomplete. After I was confident that the steps worked well (because by following said steps, the sample app actually worked), I published the sample app as a companion to the docs.
Without testing the docs through this sample app, I wouldn’t have had any idea if they actually worked, and I’d basically be an engineer’s secretary. What I love most about sample apps is that they provide an end-to-end sample of working code. If you’re working in any particular language, a simple code snippet might not run on its own (unless it’s a standalone web call to an endpoint). But a chunk of Java or PHP or C++ code will usually require a sample app to run, or an IDE to compile and run the code.
Having little disconnected pieces of code that aren’t associated within a sample app often isn’t a testable scenario. And if you have a bunch of code that you can’t easily test, how do you even know that it works? If you don’t know whether the code you’re documenting works, how can you feel good about the technical documentation you’re writing? This is why sample apps are critical — they let you know that your instructions probably work.
Getting approval to publish sample apps
I’ve discussed the importance of sample apps in writing documentation and testing that documentation. Should you also seek to publish the sample app as a companion to the documentation? For example, with each disconnected code snippet, you could point the user to the code in the sample app for context and more details.
Unfortunately, publishing a sample app alongside the docs is not an easy task. Most sample apps are distributed via GitHub, so you might need to get a company-approved GitHub repo for your sample app. To do that, there’s usually an approval process that involves Legal and other stakeholders. You’ll have to figure out the right license for the code, make sure you have approval to even use the libraries and other third-party components in the code, and more. You’ll also need to tag the code with the license in the proper way, remove any confidential files or information, and follow other security protocols for releasing the code. You’re kind of in engineering territory at this point.
Code simplicity versus more robust functionality
Another hurdle in releasing a sample app is code quality. Assuming you get approval to put the sample app in a GitHub repo, is the code even worth making available to engineers? Will the code provide a clarifying example of how to implement a technique in an app, or will the code just muddle the waters even more?
Ideally, you want to make the sample app as simple as possible, elucidating the technique you are trying to demonstrate in the docs and nothing more. But isolating the code at that level of simplicity is tough because most apps usually require some other code to load and run.
With one project I worked on, developers didn’t want to provide a sample app because they felt that any app that implemented Technique A but not Techniques B, C, D, E, and F would mislead developers. Developers implementing the feature might use the sample app as a starting point (copying the code wholesale, or using the sample app as a starting point for their app) and not realize that Techniques B, C, D, E, and F were also required.
But coding Techniques B, C, D, and E were beyond the scope of this sample app and accompanying documentation, and they made everything much more complex. Was it better to not provide any sample app at all rather than provide one that was either overly complex or which was rudimentary/incomplete?
With the video skills project I referenced earlier, the sample app was originally a fork of another Android streaming media template called Fire App Builder that had a lot of interchangeable modules. All of these modules added a lot of confusion and bulk to what should otherwise be much simpler code. But the app looked and functioned like a real TV app, with a landing page and video thumbnails. Project teams often want to demonstrate code that yields an attractive output, but they also want to keep everything as simple as possible. Later on, the team replaced the sample app with a much simpler one that didn’t have as many polished features as the original Fire App Builder app.
Overall, figuring out the right balance in a sample app is a tradeoff. A simpler Fire TV app might not even include a landing page or thumbnail view of videos, but it might be more illustrative from a code perspective. Users wouldn’t be distracted by all the other code that isn’t essential to implement for the feature you’re describing.
