I’ve been trying to understand Backtrader recently, and I was a bit taken aback by its poor documentation; which made me reflect on how I should not document my projects in the future. These are just a few of the issues I’ve encountered. While I didn’t explore the whole documentation, these problems were enough to turn me off to the project entirely because, unfortunately, I’m to busy to try and figure out the platform right now.

Lack of stage setting

The first thing I noticed was that the project assumes you understand finance, trading, and programming very well. Although it’s a reasonable requirement, there’s no indication of the level of familiarity with the subjects that are required for you to grasp what’s going on.

notes to self

  • don’t take your users’ level of competence for granted when creating a tool.
  • if you build a tool for a particular domain, at least refer the users to introductory material to lower the barrier to entry.

Lack of interpretation guidelines

The Hello Trading example code is the only one that works out of the box. However, once again, there are no instructions on how to read its outputs. It spits out a chart that says a lot in a language that you might (not) understand.

notes to self

  • when you create example code, make sure to explain what it is that the user should understand.
  • be clear about the outcomes and interpretation of the outputs of your examples.

Outdated code documentation

The quickstart should be the most natural part to follow of any project. In Backtrader’s case, the third code snippet breaks. The comments in the code are pretty esoteric and would make sense for someone already familiar with the tool.

There are plenty of references to concepts like cerebro, data feeds, strategies, and more which you can read about on other pages but that a new user wouldn’t know. When the code inevitably breaks, you have no reference for how to fix it because the general concepts of the platform live elsewhere; in Backtrader’s case, the quickstart should probably be the last piece of documentation you read, not the first.

The code snippet where you supposedly add a data feed omits how data feeds work and assumes you have downloaded a CSV on your system (this is not clear, nor it’s clear what format the YahooFinanceCSVData method accepts). A quick search leads to this forum answer. It seems that the documentation was written a long time ago, in 2017, and is static. It’s old documentation that is buggy or obsolete yet still sits on the homepage.

notes to self

  • if you have code snippets in the documentation, make sure to make them executable.
  • don’t publish outdated documentation.

Conclusion

It is not uncommon for open source projects to be a bit scattered; they’re a work in progress most of the time. It’s understandable. However, I believe that when even the documentation—which is a user’s first interaction with a project—is unreliable and confusing, it saps a user’s enthusiasm.

As a note, in my experience, all projects that claim to be “easy to use” tend to be the exact opposite. I’ve had Backtrader in the back of my mind for a few weeks before I tried to give it a serious shot, and these issues killed the mood. I don’t think I want to use any other backtesting platform either; I suspect I’ll have similar experiences with them as well.

It’s is one of those cases where you, begrudgingly, have to DIY.