Improving TopoToolbox’s documentation is a big priority for our project, but I often find that other tasks push the docs further and further down my todo list. This week I set aside Friday afternoon for focusing on our documentation, and it turned out to be fairly successful (#87, #94, #95, #96). I think this might become a tradition!
What strategies do you all use to prioritize documenting your code?
For the model that I’ve managed to reasonably well document (FRAGMENT-MNP — FRAGMENT-MNP) I have a policy of documenting any code as soon as I write it, so I won’t push a commit unless there are docs in their too (unless it’s not a user facing change, obviously). It takes a bit more time at the time, but I’m very glad I took this approach! Writing docs after the fact is tough.
I like @samharrison7’s idea but I also love the idea of ‘Documentation Friday’ because I have a lot of stuff that could be better documented. Nice idea @wkearn! I might try this out, even just an hour on a Friday afternoon.
We do have some checks set up on our repositories that ensure that every function has a docstring and that every function parameter is documented, etc. This works, but we run into two problems: sometimes we do accept an incomplete docstring that happens to satisfy the linter just to keep the process moving along, and it doesn’t incentivize the longer form, narrative documentation like @samharrison7’s example.
One thing that I tried recently is a kind of “documentation-driven development” where I created a Jupyter Notebook based on some old documentation of our MATLAB code. It doesn’t work yet, because not all the functionality has been ported to our Python package, but that means we have a list of tasks to complete, and when we are finished, we should have both code and documentation.
Let me know how it goes if you do!
‘Documentation Friday’ sounds quite fun. It’s only recently that I’ve started to devote time each week to making sure I’ve got docstrings for all of my functions, and generally improve the commenting in my code.
I’m quite new to creating code that I want other people to use; all of my previous work involved scripts that only I used. This has unfortunately meant that a lot of my older scripts are now difficult for me to understand as well.
It’s Documentation Friday again!
My main goal this afternoon is to make some progress on this old issue: Add more context to example notebooks · Issue #36 · TopoToolbox/pytopotoolbox · GitHub. We have a bunch of Jupyter notebooks that we added to document various functions, but they were always meant to be replaced with more substantive examples later. We do have a series of examples called Getting Started with TopoToolbox in our MATLAB documentation, so I think I will start by reorganizing the example notebooks to match the MATLAB docs and porting the MATLAB content to Python.
Update: Another productive Documentation Friday! Create a Getting Started with TopoToolbox guide by wkearn · Pull Request #102 · TopoToolbox/pytopotoolbox · GitHub came out of this effort. I don’t think you’ll be able to see the results easily until the PR is merged, though.
Nice 
I started digging into the Fortran bindings for the BMI docs this morning (see this thread: A new home for the BMI documentation - #8 by samharrison7), so I think that nicely ticks Documentation Friday for me!
This afternoon I’m working on text for a book chapter, which I suppose is a kind of documentation too…