Another Documentation Section Finished

It would be a fair criticism to say that Typica's documentation is not very good. In part this is because I know better than anybody where improvements should be made and it seems a bit wasteful to document something that's going to have significant changes in the future, but that's also not fair to people who would like to use the software. I've tried to create the software in such a way that how it's used generally makes sense. Sometimes I do better at that than others. Still, it's hard to tell people to read the manual if large parts of it haven't been written, so over the past couple days I wrote up another major documentation section. For this stretch of documentation writing I decided to focus on the reports that are included with Typica.

Typica records a lot of data about green coffees, roasted coffees, roasting data, product specifications, and so on. This is all information that it can make sense to filter, aggregate, and display in several different ways to gain insights into how your roasting operations are performing, but beyond this it's also a way to get at the relevant data to support making decisions. How much of what kinds of coffee should I buy? What batch size will give me the best balance between maintaining product freshness and maintaining good operational efficiency? Are there any issues related to product consistency that need to be addressed? When should I order more bags? How should I price my product? Software shouldn't make these decisions for you, but it can display information that's relevant to the decision you're trying to make which you can combine with an understanding of current and planned business activity and your strategic objectives. Some of the reports in Typica are based on analysis that I was doing against paper records prior to developing this program. There isn't anything here that can't be replicated with a paper based production system, but a database query can consider far more data in much less time. Hopefully the reports present information that is useful in making better quality decisions in less time.

I decided that reports should be documented sooner rather than later as, while I have no doubt that there are more reports that would be useful to have (I have my own to do list here), the current assortment of reports has reached the point that when people ask me about getting information out of Typica for some specific purpose, there is almost always an existing report that presents that information. Hopefully having some documentation written will help people find the reports they're looking for on their own.

Some of my favorite reports

Cost of Green Coffee for Roasted Coffee

I like this report for sanity checking product pricing. In my own roasting operations I have a wider than average range of roast levels. Some coffees are very light and can come in a little under 12 percent weight loss. Some are very dark and can come in a little over 22 percent weight loss. Most fall somewhere between those extremes. It's important to consider that loss when pricing roasted coffees and this report shows a minimum, maximum, and mean cost of green coffee to produce either one pound or one kilogram of roasted coffee based on batches of the roasted coffee item that were roasted with the same green coffees as the most recent batch. It's important to remember that this doesn't consider the cost of labor (which will vary with batch size), energy, packaging, and other overheads, but the cost of green coffee for roasted coffee can provide a useful input to a formula that takes those other considerations and a desired profit into account. This serves as a very useful starting point for thinking about what to charge.

Recent Average Coffee Production

This is a report that I consult every day when deciding how much of which coffees I want to roast. It's possible to adjust the parameters of the report to make this more or less sensitive to shifts in demand or to target company specific freshness goals.

Current Inventory and Availability Projection

This one tells me how much coffee I have and based on the rate I've been going through it, when I can expect to roast the last of that. I can run this at the end of the year to get the inventory value for the accountant which saves me a lot of time, but it's also useful for short term coffee purchase planning.

Reminders

This is an odd report. You can set any number of reminders, each with a time and a condition, and then later see progress toward the condition that you specified. For example, when you order bags to pack the coffee into, you can set a reminder to let you know that you might want to re-order more bags based on the number of pounds of roasted coffee produced since the last time bags were ordered. You can set reminders for maintenance tasks based on number of calendar days, number of hours of roasting time, or number of batches roasted. It's a really versatile tool that I hope to expand and make more visible in future versions of Typica.

Make Your Own

One of the nice things about Typica existing as open source software is that if you have a need for a report that isn't already included, you don't have to ask me to write that, wait for me to get it done, and hope that it meets your needs. The reports are each defined in an XML document and there are enough examples that any decently competent web developer should be able to look at those as examples and either modify a report that's close to what you want or write something new. And since the data is all stored in a PostgreSQL database that you have full control over, it's also possible to just connect to the database and run SQL queries directly or connect to the database from any major spreadsheet application. I would, of course, be glad to accept new useful reports for inclusion with future Typica releases and if you find yourself regularly running SQL queries or getting at the data via spreadsheet, I'd like to know about that as well. Chances are good that this indicates where a new report would be useful.