Moving conversation about documentation that started in Help me analyze my log, from a completely unturned copter over to its own thread.
Continuing from the conversation in the other thread - it seems like the main gripe that popped up consistently was that the current documentation for basic aircraft setup goes a bit too deep into the weeds for something that is relatively simple. It also seems like we try to fit a ton of info into a singular page - an example is the RC Setup Flight Mode page which goes into specifics on how to setup mixing on certain transmitters, OpenTX GUI usage, etc. It would be nice to see info like this moved to another page so that the initial setup and flight documentation is as easy to go through as possible.
One counterpoint to this. A lot of our veteran users are very familiar with the current documentation organization. Thus, any large changes will probably irk some of those users are they will need to re-learn where certain elements are located within a documentation. Ideally the documentation is searchable enough so that this isn’t too much of an issue - but its still something to keep in mind.
3 Likes
Some examples of pages that are a bit too complex (either in context or not needed at all) for initial setup (imo):
Basic System Overview
Electronics Speed Controller (ESC) Calibration
Radio Failsafe
EKF Failsage
GPS Failsafe and Glitch Protection
Dead Reckoning Failsafe
Vibration Failsafe
Dead Motor Takeoff Prevention
This list is getting exhaustive - why does the documentation go through every specific failsafe setting during the initial setup. Most of these won’t be touched by the normal user.
Another significant issue is the outdated nature of the docs. I truly appreciate the fast-paced nature of AP development, but documentation consistently takes a back seat to feature implementation and improvement, which makes for a frustrating user experience.
As an example, I recently discovered that the Betaflight-oriented frame permutations were not included in the documentation and did a little image editing to fix that, but noticed in the process that there are quite a few frames missing from the page. I thought it’d be an interesting challenge to fix that while helping improve the motor/ESC doc overall and am happy to help with such things occasionally, but there’s probably a better way to document new/added features than relying on users to notice they are missing.
The Lua scripting page is another sorely outdated doc that presently only references a small subset of the available bindings with only a cursory mention of how to see what else is available, and users are left to scour the examples folder to see any given undocumented binding in use. Credit where it’s due - the provided examples tend to keep pace with new bindings, and that’s an excellent start. It may well be possible to use the annotations in ardupilot/docs.lua to auto-generate some wiki documentation and maybe even link to the examples in which a given binding can be found. That way a dev could add a binding and its associated annotation (some of which are lacking) and never worry about a wiki update.
1 Like
I never want to advocate for less documentation - but I think the outdated nature of some of the documents is because of how convoluted the structure is and how much information we try to cram onto a singular page. Also - trying to have documentation for all the older versions of ArduPilot is a bit of a pain (but definitely needed). Would be nice if we could at least move on from pre-4.0 notes on the basic setup pages.
2 Likes
Also for what its worth - you literally can not go through an entire ArduCopter setup by clicking “next” in the documentation. You end up in recursive loop learning about all 25+ autopilots.
3 Likes
Also wondering if there is any desire to move to another service like GitBook? It seems like it might making editing the documentation a bit easier - which may lead to keeping the documentation more up to date.
2 Likes
Completely agree that 3.x is effectively deprecated/unsupported, and documenting its use only adds to confusion for the vast majority of users.
GCS features that target 3.x (like auto analysis of logs) should also be deprecated and removed, but that may be a separate topic (and rant!).
2 Likes
Maybe its easier to “start from scratch” by starting to build up documentation in GitBook and then slowly transitioning over. Main priority being getting all the main documentation for a simple ArduCopter, ArduPlane, ArduRover, etc. transitioned first.
1 Like
Also just noticed that GitBook is getting OpenAI support soon - which would be really cool!
True, but I would be all for a different format. One thing for sure is good or bad new users have to be funneled to the Docs somehow before they launch their craft. Not sure how that happens when it’s common to just skip a screen in MP’s Mandatory Setup.
Search within the Wiki’s is poor too. It’s by far better to just Google the question.
2 Likes
I think a good place to consider starting is a self contained “getting started guide” (this could be in gitbook or whatever) that isn’t encumbered by references to out of date feature or hardware. It could still have links at the bottom of the page for more information on advanced setups or something like that.
One other thing that in my opinion needs to be reignd in a lot is in text hyper links. It’s just not good readability to put important links in the middle of a paragraph like that.
For instance the official download page for mission planner is really weird and unofficial looking. The official download link is just a hyperlink in the middle of a paragraph. And the download link isn’t even on the first page about mission planner that someone would come across searching for it.
I often find myself doing just that to find a page or section I already know exists.
1 Like
To your worthy effort, I have worn out the keyboard with “arducopter motor order”.
3 Likes
and mine has permanent holes in the keys that spell “GPS for yaw.”
2 Likes
GitBook has really good search (and even better with OpenAI integrated) - so hopefully that helps in that regard!
I have no clue about pricing structure and whatnot - so that is something to look into.
I know we are team ArduPilot here - but PX4 uses GitBook (i think) and I am honestly a fan of their documentation structure/simplicity.
1 Like
I would like to get some feedback from the main developers regarding whether they think this this a fruitful task or not.
Absolutely agree that we should get some feedback from @hwurzburg and the team regarding a complete overhaul/migration to another platform.
We are always open to ideas for improvements. Be aware that most of the wiki effort is done by one part time person. The wiki covers a lot of complex and advanced features and I have tried to get it organized such that basic setup and tuning is covered in the red highlited sections.
An important factor is that the user base covers a very wide range and even wider range of vehicle styles. What would satisfy one frame/user will be inadequate basic setup for another.
I did create a basic fpv plane setup Basic FPV Plane — Plane documentation a couple of years ago(which probably needs refreshing)…perhaps a basic miniquad one is needed…will put that on my list,but my major efforts are keeping up with new features and getting them documented.
The search feature sucks, but it does work, it just returns every match and cannot be refined.
I am open to any suggestion on improving navigability but bear in mind any individual’s perspective is just that individual .
As to a new platform, that would be a major undertaking, but one I am not opposed to in general, if resources to do the move can be identified and funded. The resources part is the big thing, and I would oppose a start unless we know it can be finished.
Old versions: I occasionally try to eliminate older versions info but we need to keep at least two stable versions in the wiki since many commercial users will not update more frequently…feel free to point out anything older than 4.1 version info and I will archive it.
4 Likes
I would be willing to put in a good amount of time for the transition to a new platform - as I think it will help in the long run. This is definitely an undertaking that would probably require close to year for a full transition - but most documents can probably be transferred easily. Just would need to figure out what is prioritized. My experience is mostly with ArduCopter (and some ArduPlane) so I would mainly be able to assist with those.
Personally, I think that if we are going to dedicate a good amount of time towards this we might as well switch platforms at the same time.
The funding is something we would have to discuss depending on what platform is chosen.
1 Like