Disclaimer
The ideas expressed here are my subjective opinions based upon 40 years of software development. I've spent a considerable amount of time documenting or explaining software to people with a wide range of experience with a equally wide range of success. Documenting technical information, either hardware or software, is a difficult task and more often evolves over time. I don't have clear guidelines but do have a few principles that have been helpful, and I know what feels wrong or right when I find it. In any event, these are my opinions and yours may vary. No offense taken or given.
Petoi Doc Center and the Bittle X Assembly
My experience with the Petoi Doc Center and the assembly process for the Bittle X robot is the focus my comments here. The Petoi Doc Center has lots of links and documents on a wide range of topics. This is both an advantage and a disadvantage. The advantage is the range of information available to the user, The disadvantage is that all that information needs organization and maintenance. For the majority of the Doc Center cross links can significantly reduce the organization and maintenance. Users won't be distracted by following the links to different pages ... except when following installation or assembly instructions. Then they want straight line, sequential steps with no deviations. Don't refer them to another page (that saved you maintenance effort. Remember, you're saving their time, not yours.) Whenever possible, verification steps should be used for positive feedback. Background information or justification should be avoided until after the final step. After things are working they'll appreciate the why and if things aren't working the explainations won't be all that helpful.
Keep the target user in focus. For assembly instruction it's the least experienced user. More experienced users will skim over the basics with little effort. Less expereinced users will be easily confused.
Identify things early and be consistent. Is it a sholder or hip? Leg or arm? Or just joint1, joint2, etc. Honestly, the joint numbers still doesn't make sense to me. In my opinion they should be numbered so that I can tell you which is which off the top of my head. There are only 8 servos. Zero is the head and the rest follow sequentially, left sholder-arrm, right sholder-arm, left hip-leg, right hip-leg. I can identify which one given the number or the description in my head. I think the average 12 year old could as well. There are only 8 servos but there are joint numbers 9-15 that hop around the body. This kind of complex numbering should come after initial assembly.
So, as a concrete example, let me describe some of my thoughts on the Bittle X assembly and go into some detail on the calibration instructions.
That package contains a parts list and I do go through these lists and locate all the parts. I was successful but there was an extra part. There's a spare servo but there's also a tiny nylon servo reduction gear that's not on the packing list. (I hope we aren't expecting to open a servo and replace a reduction gear.)
The instructions in the package give me the QR code that brings me to the Doc Center website that I've nver been to before. I'm looking for assembly instructions for a Bittle. (At this point I'm not aware of the distinction between a Bittle and a Bittle X.) The page has the Getting Started link and that links to the Bittle page. I quickly get past sections 1 and 2 with no cause for alarm.
Principle: the product should have a clear means of identification and the user instructed to find it.
As it turns out, if I had followed the Bittle X link I would have ended up on Step 3 which tells me:
"The assembly process of Bittle X is the same as Bittle except for the wire connection on BiBoard."
This has a link to the Bittle assembly section 3 because they are the same, right? But as soon as I go the page I realize they aren't. The heading on the page says, "3.1 Start with the Unassembled Kit" but my Bittle X is partially assembled. I now must read through sections 3.1, 3.2, 3.2.1, 3.2.2, 3.2.3 and stop at section 3.2.4 and forget everyting I just read.
Everything went fine up until section "3.2.7 Battery" where this note appears:
The controller board is already fixed on the body in the following picture. You can finish the Connect Wires chapter and then return here.
This is what I think is a major flaw in presentaions, instructions, and documentaion. This skips a step and tells you to read the instructions out-of-order then return here. But it gets worse. We were told when we came here that the only difference between Bittle and Bittle X was the wiring. What we wonder is where are the wiring instruction for Bittle X? What we don't know until we read past the NyBoard wiring, which doesn't look anything like our board, is the the BiBoard wiring is shown. But then the pictures revert back to the NyBoard! Those photos show the wire wrapped around the board support posts, which is physically impossible for the BiBoard with the hat. Nor have we been shown how to install the board (is the hat up or down?)
I won't go further here into my experience with the wiring other than to say it was extremely cramped and fraught with peril. It was as a result of this that I desperately wanted to verify that the wiring was electrically sound before I went any further.
After tearing down and reassembling the robot 5 or 6 times I found a way to do it easily and reliably. You first need to know that the hat faces down, not up. You might deduce that from the photo of the Bittle X wiring. But it should be pointed out.
Second, and most important, don't screw the board to the frame until after you connect the servo wires. You have more slack in the wires and more room to connect them to the proper pins.
Third, the target user doesn't know positive or negative or ground or color coding. They do know black from white though. A simple guide, "Black on top, pin closest to the main board with the big silver square" leads to the second guide: the pins are numbered and should be used. Left front arm goes to 32, left sholder goes to 33, head goes to 19. Isn't this the reason the numbers are on the board?
OK, this is long enough on this. Once more, these are my opinions and I'm retired and probably a little out of step. Next post I'll try to tackle the calibration process.
I agree with everything that was said here. I just finished putting my Bittle together and found the documentation much less "linear" than I would have liked. I.e. there was a lot of jumping around between different web pages. It all worked out in the end but it was much more painful than necessary and might put off less determined folks.