Two weeks ago, Julia Furay and I presented a poster at ACRL 2019 about automating a library outreach initiative with Python. The presentation went well; people seemed interested in the project. But talking to librarians at the conference really got us thinking about how to make our code more reusable. If others want to use our work, there are probably some steps we could take to make that easier.

One thing we could do is to document the project better. Leading up to the conference, I put a lot of comments into the code to make it more understandable. This is a good step, but it presumes that the reader will be able to figure out the code with the help of some comments. In reality, some librarians will be able to do this, but not everyone.

Besides understanding the code, there is also some setup that needs to be done before the program will run. This includes things like installing Python, cloning a git repository, making a virtual environment, and installing dependencies. Most of this will be non-obvious to someone who does not deal with these issues regularly. Creating a README with some instructions on where to start is a good idea too.

Nevertheless, there’s a balance to be struck. Lengthy instructions on how to set up a development environment would be overkill for a small script like ours. But being a bit more thorough with documentation makes the code accessible to more people. You can see our attempt here. Feedback is welcome.

This entry is licensed under a Creative Commons Attribution 4.0 International license.