We are very much still at the “just write a little code” stage. Should we be further? Yes. I…did not expect to spend as much of my time on the manufacturing side of things.
It will get better.
Part of the reason that Kaleidoscope’s core is built around a plugin system is that it makes it possible for the folks who are happy to write code to build reusable components that other folks can reuse with a trivial recipe, rather than having to rewrite the functionality. At the same time, folks are working on a GUI.
Part of the reason for sending out PVT keyboards to customers was to figure out which teething issues need to be addressed first. For me, choosing between a default firmware that works, but is underdocumented and a default firmware with copious customization documentation and reliability issues in the default build is a pretty easy choice.
I don’t think anybody thinks that “just write a little code” is a good end-state. (And if they do, I’m happy to debate them.) It’s just one step along the way.
All of my experience indicates to me that documenting code as it’s being written, rather than waiting until it’s stable, does not result in taking longer to get it stable, and leads to better quality at all points in time. Especially on open-source projects, where neglecting documentation leads to a situation where many people are effectively prevented from contributing, and others try despite a lack of understanding, and almost inevitably introduce bugs that could have been avoided.
You’re not wrong. It’s something we need to get better at.
I’d love to talk about concrete steps to improve the situation. One of those steps is figuring out a clean, simple, standard way to write function-level documentation and automated tests for it. I know what the right answers are for Perl, Ruby and Java. In general, I’ve not seen good examples in Arduino-land and I don’t know the C++ world well enough.
Do you have recommendations? Does anyone else have recommendations?
Though we’re spinning out on a tangent from the original topic here. I’m going to reparent these posts to a new topic.
How about aiming for an easier target first, and just add a comment that describes the purpose of each file. Then, when a bunch of those are done, comment some functions. Just a basic description of what each part does and/or why it’s there, starting from the highest level. Try to formalize it, and it could take much, much longer to get anywhere.
I’d love to help produce documentation for Kaleidoscope, and I’m generally good at it (especially unambiguous step-by-step instructions — I worked in QA for quite a while, and had to rewrite many, many bug reports). But right now, I don’t have enough to get started even trying.
Indeed, I very much don’t want to turn this into a major discovery project for documentation systems.
I was mostly thinking of starting with the core of Kaleidoscope. There are only a couple c++ files and only a handful of header files. We’re only talking about 50 functions across the entirety of the core.
Over on the plugin side of things, we’re near that standard - I believe that most plugins are a single class and have a README that describes what the plugin is and how to use it.
Just as a note, you don’t need to do that. You can “Track” any post, just by clicking on the button that reads “Tracking” or “Normal” or something else on a line by itself at the end of the post.