Reference Sections

An overview of what the Reference section should consist of within each article. This should be kept in mind when creating content for Wednesday.

By nature, an article shows a reader how to use an API or technology in a sample project, to solve a single use case.

You want readers to actually apply the API or technology in their own projects, to solve any use case.

To do this, it’s important to periodically have reference sections in your article to explain other things that the reader can do outside of the scope of your single-use case.

For example, there is a database library in Android called Room, that has a set of operations.

Imagine you wanted to create an article to cover Room operations actions. You have a few options:

• Try to cover all possible operations [BAD]: There are a lot of operations, so that would be quite difficult, and would make for a long or boring article.

• Cover the most useful operations, and ignore the rest [BAD]: You could choose a few operations to cover and ignore the rest. This isn’t ideal, as you wouldn’t really help the reader: you’d be leaving them to discover and learn them on their own, without any assistance.

• Cover the most useful operations, and add a reference section [GOOD]: This leads us to the best option. Choose a few operations to cover, then add a short reference section to show the reader what other operations are available, and where they can learn more about them.

When developing your article, ask yourself “what does the reader need to know about this API or technology, outside of the scope of what I will show them with my sample project?”

Then create reference sections for those.