Suggestions for the Arduino Project
Standard Documentation Templates
Topic: Standard Documentation Templates
(Read 645 times)
Standard Documentation Templates
Feb 05, 2018, 05:26 am
I'm a hobbyist, and even that is probably giving myself a little more credit than I deserve, so that's where this is coming from.
I got in to mcu development when it was still significantly more expensive to buy Arduino boards and the like than to build out from the mcu, so I learned the way a lot of people did, by reading datasheets for the different ics that I wanted to use. In the beginning, that was information overload. I remember feeling like I was way out of my league looking through all the specs and pages and pages of other data that I didn't understand all (or much) of. However, I did finally learn what parts mattered, and I got better at using them. Once I did, it was rare to not have the information that I needed to work out how to get things going.
Fast forward to 2017, and Arduino boards, and modules of all sorts, are cheaper than the bare components to get something like an ATMega minimal system setup, and the amount of information available for the more common components is amazing.
The problem that I'm seeing is that the information isn't standardized in any way. I keep finding myself reverse engineering some of the very common libraries and it's taking longer than it would take to go to datasheets and build out. One example is libraries that do pin assignments in the library files and then not documenting what those "default" pins are, or how to assign other pins. I've ended up digging through the library files to find that stuff far too often, and I don't think a lot of beginners are going to be able to do that.
I do realize that it isn't possible to control community created content. However, I think it would be a great start to implement a documentation template that would include all of the information that a complete beginner would need to get examples running.
The fact that so many libraries adhere to the Arduino file structure to make installation easy suggests that adoption would be noticeable at the least. In fact, I would imagine a good number of the people working on these libraries would appreciate a template. Documentation is the most boring part of a fleshed out project.
I've already been desoldering caps and swapping resistors so that I can use AT7 and my ICE, but I do love the Arduino "make it easy" mentality when it comes to playing around with ideas. I managed to get a nano, a small oled display, and an ethernet module setup and doing CDP and LLDP frame decoding in less than a day. I can plug this thing in to a piece of network equipment that is running cdp/lldp and get useful information about it from a small handheld device that will run for hours on a single 18650. That's pretty nice. I still don't understand this enc28j60 in great detail, and I'll have to learn a lot more to build a reliable device, but I quickly built a PoC and Arduino made that possible.
Re: Standard Documentation Templates
Feb 05, 2018, 08:47 am
The natural template is the official documentation found on this website. Generally I think it takes the right approach of being very beginner friendly. Historically the greatest fault with the Arduino documentation is that it went a too far in that direction to the point of being less user friendly by not documenting parameter and return types or even lying about them. Over time we have worked to get this fixed up but it has been done in a piecemeal manner which means the issue still exists on some pages and the format is not consistent. So I think the best way to move towards your goal is to work to improve the Arduino documentation. This has recently become much more efficient by putting all of the Arduino Language Reference content in a GitHub repository, from which the web pages are generated:
There are plans to do the same with the Arduino Libraries reference pages eventually but unfortunately for now we are stuck with the old inefficient system of submitting issue reports with the suggested changes and then waiting for someone from Arduino to implement them. This can be a very slow process and often they don't get it right on the first try but if you're patient and persistent it is possible to make it work.
I think this discussion would naturally turn to doxygen but I find the documentation generated by doxygen to be very much not friendly to the average Arduino user. There's something to be said for being forced to directly interact with the same documentation the user will be reading. When you're in the programmer mindset everything is documented by the code so you slap in a quick comment and call it good. If you actually look at the documentation produced by these comments through the eyes of a beginner who will never see the source code then it would be clear where the documentation is lacking.