Modernized INAV Documentation

[robotgoat]

Hello all, I've noticed that as the INAV project has grown and become more complicated, especially since VTOLs are now supported, the documentation is too spread out, clunky, and not very user friendly. To address this, I made a documentation website similar to that of Betaflight's.

The site is made using Docusaurus 3.8 as of now and only has the bare minimum. I took some creative liberty in reorganizing key features of INAV into a "modules" section. There's also a quickstart section that is a WIP since I don't have the ability to build and fly any of my aircraft. There are still a few sections and modules I have to complete, but the gist of the documentation is there.

If the community deems this kind of documentation format for INAV to be worthy, I'd then like to know if it can be used to replace the wiki and docs markdown files, and have the website merged into the offical INAV github pages. Currently, inavflight.github.io takes you to the wiki, which is very clunky and out of date in some areas.

The current working documentation is can be found here: https://www.spiffygoose.com/inavdocs/

[sensei-hacker]

Thanks for that! It looks really nice. The documentation is important and it could sure use some attention.

A challenge is that documentation gets updated pretty often. For example, I know that I and @CREASE-gum-EAR have both updated different parts of it today. I don't know who else may have updated some of it today. I see Docusaurus makes a static site. We need something that allows different people to easily make updates. I'm thinking maybe a hybrid approach, combining what you've done with the convenience of a wiki might work well.

This is just an initial thought to move the conversation forward, but I'm thinking maybe use the awesome organization and menu that @robotgoat has made, with the actual content of each page being the wiki. So the navigation links load the wiki pages, which can be edited just as easily as they are now:

That way someone could click to quickly edit the Blackbox page to add some information, or correct something, just as they do now.
On the left side would be the excellent navigation menu.

Note that's just one idea off the top of my head on how to combine the benefits of both. I'm sure others will have more thoughts.

[robotgoat]

Thank you for the feedback! Docusaurus actually has that feature built in. I'll enable it in the next push of updates as I transfer the content from the exsiting doc sources. I've done a lot of proofreading and have corrected many grammatical mistakes in the existing docs that might be unclear for new readers, so I really think my edits will be beneficial!

I totally agree that the legacy wiki should be kept, especially for information pertaining to older versions of INAV.

[CREASE-gum-EAR]

I love INAV. About a year ago I wanted to help with documentation as I write reports for work that have to be read by normal people but also need to be technical. My first step was to catalog all the wiki pages and the master/docs pages that are floating around. I then created the wiki menu and I listed all the pages I found and grouped them by topic. Then I started consolidating material with a single link in the menu for each topic. For the advanced topics, I moved the links to the bottom of each topic page and explained them. I didn't delete anything, just some rewording. Its now been 9 months since I made an edit but that facebook post kicked me in the but to get going again and I just did the Mixer Tab and the Outputs Tab pages.

I don't have any preference on what would be better as far as approach, but my goal was to finish the consolidating effort. Then go through it all top to bottom and modernize the information, fill gaps, and preserve old info with collapsible sections for old INAV versions for those who need it. As for editing preferences, I do enjoy how easy it is to edit the github wiki and would like to retain that ability. I am happy to just do content updates and you all can do the pretty stuff.

[robotgoat]

I echo the same sentiments! Like you, I found that there's a major discrepency between the docs in the repo and the docs in the wiki. Often times many people will refer to what has been called the dev docs, so it defintely makes sense to consolidate the two.

Docusaurus makes it very easy to make edits the same way you can in the Github wiki. Since the website is also hosted via Github pages, the principles are all the same. I hope this will make it easy for you to contribute to what I think is an improved documentation format!

[sensei-hacker]

Just an FYI on this topic -

The original idea was that the docs/ folder is basically for developers / contributors and the wiki is for users. That's not written in stone though. Things can change.

[MrD-RC]

The dev docs do have useful information in there. But also a lot of information that isn't needed. Ideally the Wiki should contain all the relevant information while being easier to understand and also filter out what isn't needed unless you're doing development. But, there's nothing to stop having a link to relevant dev docs at the bottom of a wiki page.

With regard to versions. I did try to have some relevance for versions in the Wiki. I think if you check out the RTH page. It says which versions of INAV certain RTH methods work in. Also with features like two stage climb first, it says which versions it was introduced. I think little things like that go a long way. It will hopefully limit problems relating to features in certain versions. It wasn't long ago that I heard someone is still using 2.3.

[robotgoat]

Wow, MrD thank you for the feedback! I follow you on Youtube! I agree with @CREASE-gum-EAR that the dev docs are just as useful for normal users as the wiki. I've often experienced that guides and forums will refer to the dev docs more than the wiki. The Betaflight docs are the same way as I'm often refering to things in the "dev" section of their documentation. I just made sense to combine the two instead of having them in two different places.

Regarding changing things, I totally agree that the existing docs should be left as they are, as refactoring them would cause more headache than is necessary. Instead, my idea is that starting with the current release (8.0.1), the docs undergo a transitionatory period to the Docusaurus website. For people who use older versions, they can continue to refer to the original markdowns from the Github repo.

Docusaurus makes it very easy to do versioning too, so I don't think that will be an issue in future verions of INAV.

[MrD-RC]

I'm not sure on this to be honest. There should only be one set of user oriented documents. Currently that is the Wiki. Having multiple "official" user oriented document repositories would just be confusing. There should be only one.

The dev documentation 100% should stay as it is though. As it is explicitly linked to tags in GitHub. I also don't think that all information in the development docs is useful for pilots (I really hate the term "users"). There is quite a lot that is useful references for development. For example the table of OSD elements with their IDs. That would only be useful if you're editing your OSD with CLI. But who's that crazy 😉 Don't get me wrong. There are lots of useful pieces of information in the development docs for pilots too. But it should be cherry picked. To go in the pilot oriented docs.

[robotgoat]

@MrD-RC I would be what's considered a fairly normal user of INAV and I almost never reference the wiki docs because it's just so user unfriendly for the current working version. I think the current documentation layout is confusing, which is what the Docusaurus site aims to address.

A lot of the information I get is from Google searches that lead me to Youtube video that reference something in the dev docs and/or a random line in the wiki. Painless360 makes a lot of INAV guides and I later found that most of the information he gets comes from the dev docs, so I really think there needs to be a way to consolidate the two. Betaflight and Ardupilot both have excellent documentation organization, so I hope INAV can have it too.

Things like tables and variables are important, but are't always necessary for pilots who want to setup an aircraft and fly. I addressed this by making an appendix for these variables. Having the search bar will also make it really easy to find mentions of CLI variables through the entire docs. I actually didn't know you can create custom OSD elements before I went through the docs. Since I now know that feature exists, I definitely plan to use it on my next build. I think other pilots will find great utility in knowing that too. Making that kind of information easily accessible is my goal with this.

A good example is one of the recent discussions here where a pilot asks about how the autoland feature works. There's a page specifically explaining that in the dev docs, but in this case the whole thing is relevant to pilots who really need to understand the functionality for safe flights.

[MrD-RC]

With regard to appendices. They should just be links to the dev docs. Then it keeps the most relevant information.

I agree the .md doc on Auto land, and Geozones for that matter. Should have had wiki pages.

I think some things in the wiki is structured well. The modes for example. But there is always room for improvement. I don't like how some of these new document sites are structured. It makes it difficult to find what you're looking for.

[sensei-hacker]

I can see what @MrD-RC is saying - the version control is more visible for the docs/ folder, because we almost always use pull requests for that.

It might be worth noting the wiki is also a Git repo, version controlled with commits etc. You can clone it like any repo:

I have a local clone on my laptop.

Each page has a history button at the top where you can see what changes were made, just like any other file in a repo.

There are some differences - you can commit changes to the wiki without the pull request being approved by a maintainer. That makes it more convenient to make small changes. That means that most of the time, the history is in the commits - often there is not a pull request.

The wiki is feels more dynamic, more conducive to change, because it doesn't require a PR. There may be some benefit to the separation based on that.

[Jetrell]

If it helps to know when organizing. @robotgoat @CREASE-gum-EAR. From the Wiki. Everything in the PID Tuning, Modes and Failsafe is up to date as of this year. With most of the OSD and GPS documents also up to date.

Edit: This one in the Tuning is old. Its an example of what to do with it.

@MrD-RC @sensei-hacker
In the Wiki, there is a lot of older stuff there which crosses over into older Git docs. But its a hard one to know when to just leave the past in the past. Because it makes it harder for new users to find what they are after. Due to them having no idea whats old and what's new
Most just want info relevant to the last few releases.

[MrD-RC]

To be honest. I'm not convinced moving the docs to a different site is a good idea. Especially if the core INAV team doesn't have ownership over that site. I've not had time to investigate how anyone can contribute to, and change those documents on the other site. Though I do agree that a search option is useful.

[robotgoat]

@MrD-RC Sorry if I it wasn't clear, the repo that the site exists on right now is forked from the inavflight's inavflight.github.io. My intention is to merge it into that repo so that the INAV dev team has ownership to continue adding to it for INAV 8.0 and onwards so that information is more easily accessible and professional like Betaflight's documentation is.

Would you like me to submit a pull request for that repository so the dev team has ownership?

[MrD-RC]

I also think that if the docs are moved. They should replace the wiki. This means not just starting at version 8. But keeping the relevant information for older versions as highlighted above. There are still people flying version 2.3. There are lots of people still flying version 7, as they didn't like the updated altitude controller.

[MrD-RC]

You keep mentioning BetaFlight's documents. I don't think they're well organised at all. Just look at the Guides > Current section. Everything is just dumped in there with no organisation whatsoever ever.

Other than the Welcome section, it's a mess.

[robotgoat]

@MrD-RC we can certainly migrate all the legacy documentation from earlier versions over as well. I'll parse through the wiki and sort out the versioning manually and then use Docusaurus's versioning feature to nicely organize it. I agree and like having all the information easily accessible instead of having them scattered in the wiki. It will take a bit more time, which is why I had initially suggested to use Docusaurus for v8+. However, I'm fully for using it for all versions too.

[robotgoat]

Hi dev team, just wanted to bump this discussion again as it hasn't seen much activity or response from my PR. I've noticed that the fast growing and actively developed Rotorflight flight controller software has a clean website made using Docusaurus that really makes getting to know the project from an outside perspective real easy compared to the layers of INAV markdown files, many outdated, buried in the repo's docs folder and wiki section.

I'd like know if the greater dev team is actually interested in revitalizing the documentation structure into the Docusaurus website? I really think it would make the project look better and be taken more seriously by third party board manufacturers. All the major FOSS FPV projects have a website eg Betaflight, EdgeTX, Rotorflight, Ardupilot, PX4. INAV is the only lagging behind in this important aspect.

Thanks!

[MrD-RC]

Me personally, I would prefer to keep the documentation on GitHub. I just see having stuff on a different website will fragment things even more. As, has already been discussed. Some documents need to remain on GitHub.

[robotgoat]

I think I had suggested that the Github markdowns not be removed, rather the current and future documentation migrate over to Docusaurus. I disagree that it would fragment anything. If anything, it will make searching and organizing information much much better than the current system.

Do you think migrating the current and future docs to Docusaurus is still not a worthy upgrade to INAV and its public image?

[sensei-hacker]

Me personally, I would prefer to keep the documentation on GitHub.

I agree, and that's part of what makes Docusaurus attractive - it would be hosted right here in our Github.
At least as I understand it.

See comment above

I see it can either be a folder witin the INAV repo itself (github.com/iNavFlight/inav/docs_web/), or it could be a peer to inav-configurator, inav, blackbox-tools etc, being another repo under the iNavFlight organization.

Documentation for the Mono repo (folder) option

In the same way that we have a tool which converts settings.yaml into settings.md, this tool would compile "source" markdown files (in our repo) into the final html, hosted via GitHub Pages as part of our Github. This could be built automatically by Github actions, in the same way that a PR triggers building the binaries.
Building Docusaurus pages automatically with Github Actions

It would be much like the existing automatic parsing of Markdown that Github provides by default, but better.
We would store and edit the Markdown (.md) files as we always have - they would just be displayed in a much nicer way.

[robotgoat]

@sensei-hacker

Correct, the docs would be hosted in the project's repo. I hadn't considered using the Mono repo option, but that is a solution as well albeit rather messy. It isn't exactly a simple drop and build either because Docusaurus requires mdx formatting. I ran into this issue as I was copying the markdown contents into new Docuasurus pages. There are some special character restrictions with mdx that will prevent Mono repo folders from being a simple operation. This is why I think the existing docs should be transcribed to be Docusaurus friendly, which will allow easy maintenance for future docs as INAV changes.

I think it makes sense to keep the existing markdowns as they are in the main project folder, but have the transcribed Docusaurus website's contents in the inavflight/github.io repo to keep things organized (this is where I submitted my PR). Since the domain inavflight.com is under your control, it can easily be linked to the Github project page for the Docusaurus website.

Both Betaflight and Rotorflight have separate repos for managing and hosting their Docusaurus websites.

[sensei-hacker]

It's been discussed lately that Google doesn't show results from the wiki and rarely from docs/. So the official INAV stuff is mostly invisible in search. For most searches related to INAV, Google mostly just returns articles by Oscar Liang. Or worse, random Reddit posts.

A Docusaurus site might fix that.

[Jetrell]

Yeah. It might be good for that reason.
The way it is, makes AI searches absolutely useless. Providing information that is wrong most of the time... I spent half an hour last week debating with a certain AI bot over its incorrect interpretation of a certain INAV function, until it finally conceded it got its understanding wrong.. Any wonder users get confused.

[robotgoat]

I haven't been updating the site since it initially seemed like there was no interest in using it. If there's a renewed interest, I'll finish transferring the latest information from the wiki and docs/ markdown files and version it in preparation for INAV 9. Please let me know so I can finish it in earnest!

[MrD-RC]

I still think that this should just be the Wiki. Maybe select parts from the markdown docs. As they are more technical than a user guide.

[sensei-hacker]

Sounds like we have general agreement.
So @robotgoat it sounds like the next steps would be to refresh with the latest changes, then we merge your PR in the GitHub.io repo?

For now, we would leave things in docs/ and our new GitHub pages repo (github.io repo) would "replace" the wiki. After we've had time to use it and get used to it, maybe some things like VTOL.md should also be moved into the documentation repo. But we'll try it with the wiki contents first.

Am I missing anything?

Thanks again for your hard work!

[robotgoat]

@MrD-RC I see what you're saying now. I was under the impression that because of the overlap and grayness of distinction between what's considered technical and what's more superficial as @sensei-hacker describes, we would want to include information from both the wiki and docs/ in the new website.

Is there then no desire to fully port over the docs/ to the website despite there being a lot of useful information that describes the underlying code that may help users? I think having all that information in docs/ be searchable would still be a huge boon for not only devs, but also for users.

[MrD-RC]

Sure, we should include some information from /docs in the new pilots guides. But not the crazy technical stuff.

I totally get where you're coming from @sensei-hacker. But I think if you can do it in the main UI of Configurator it should be documented to a level that people can get what it's doing. You're right, there are many levels. But there's nothing to say that we can't have the documentation work in that way too.

For your mixer example. The first section could just be about applying a default mixer. Then how to check the surfaces are moving the right way. Then how to remedy it if they aren't (usually a quick toggle on the outputs page).

The next section on the mixer could be about adding another line in the mixer. For example a pan servo.

Further down there could be an Advanced Mixology section. Which could delve into

• using a servo for throttle
• different weights and speeds
• differential thrust
• working with the IPF
• selecting custom timers

But it doesn't need to smix or lowpass filters etc. That example could be over separate pages, if too long. Or can each page have a contents menu at the top?

[robotgoat]

Got it! Thanks @MrD-RC and apologies for the confusion. I have a better idea of the organizational structure you prefer and will implement it.

Another example where all the magic happens in the mixer is for VTOLs. That of course is its own page with perhaps references to advanced mixer information.

[sensei-hacker]

Sounds good, Mr D. I agree that's how much of the documentation should be - start at the high level and go deeper as you go deeper down the page.

I don't know that there is a clear line where you say "stop, that's technical so it can't be here - it has to be in the docs/ folder rather than the documentation repo".

Or can each page have a contents menu at the top?

As I understand it, Docusaurus automatically puts a contents menu on each page at top right based on the headings. On the other hand, one of the reasons HTML and the web was invented in the first place is so you don't need to have everything in one huge file. Rather, you can easily link to documents that go into more detail about specific things.

The general consensus on the UX stack exchange seems to be something like a page should give a complete answer to a single question. Avoid "wall of text", they say, using links to related pages. So that users don't see a 5,000 word document and decide "I'm not reading all that!"

[MrD-RC]

Another example where all the magic happens in the mixer is for VTOLs. That of course is its own page with perhaps references to advanced mixer information.

Oh totally. VTOL is it's own beast and in-depth subject on it's own. So would definitely deserve it's own page.

As I understand it, Docusaurus automatically puts a contents menu on each page at top right based on the headings. On the other hand, one of the reasons HTML and the web was invented in the first place is so you don't need to have everything in one huge file. Rather, you can easily link to documents that go into more detail about specific things.

The general consensus on the UX stack exchange seems to be something like a page should give a complete answer to a single question. Avoid "wall of text", they say, using links to related pages. So that users don't see a 5,000 word document and decide "I'm not reading all that!"

Yeah, that makes sense. It's cool that it adds contents. TBH, I'm of two minds whether a single page of multiple pages are better. Sure, a wall of text can look intimidating. But there's a risk that the thing you're looking for isn't on subpage-c, it was missed as it's on subpage-b. Or you could have tens of pages with a single paragraph and keep on having to navigate. There are pros and cons to both approaches. I'm also sure there are ways to make each approach better for the reader.

[sensei-hacker]

Robotgoat I did a PR against your sample repo, from which your PR to the INAV repo comes.

needs to be owned by the INAV project and editable by INAV contributors

It will be in our existing repo that hadn't been updated for the last eight years, at https://github.com/iNavFlight/iNavFlight.github.io

You will have the same control and editing ability that you have for any of our other repos, such as:

https://github.com/iNavFlight/inav
https://github.com/iNavFlight/inav-configurator
https://github.com/iNavFlight/inav/wiki

[sensei-hacker]

4.0?
Is that a typo for 8.0 or 9.0?

[robotgoat]

Yes, I'm porting over the wiki starting from INAV 4 so there's version history for users who are using earlier builds. Mr D mentioned that it'd be a good idea to have the documentation pertaining to a few versions prior to the current version. I'll be adding the things for 4.1, 5, 5.1, 6, 6.1, 7, 7.1, and 8 shortly.

[Jetrell]

@robotgoat I'm not familiar with all the workings of docusaurus. In the case of changes that will be made to the INAV Wiki at a later time. Is there a means to auto-generate or migrate them across to the web page? Or does that have to be done separately.

I generally add more setup information to the wiki if someone asks about it on the INAV discord channel.
When features are added by contributors, they very rarely contain an indepth explanation of how that feature works, it's mostly a basic write.
More guidance is often added at a later time. Whether for tuning, or possibly a better understand of what that feature may do under specific conditions.

[robotgoat]

@Jetrell Unfortunately there's no easy way to migrate the wiki contents to Docusaurus that I know of. I've currently manually migrated INAV V4.0.0's docs over by checking out the the commits from the wiki that only pertain to 4.0.0. Then I start transferring the markdowns and making sure the formatting and links are correct. The same process is being applied for the rest of the INAV versions until the docs have been fully migrated.

[sensei-hacker]

@Jetrell Unfortunately there's no easy way to migrate the wiki contents to Docusaurus that I know of. I've currently manually migrated INAV V4.0.0's docs over by checking out the the commits from the wiki that only pertain to 4.0.0. Then I start transferring the markdowns and making sure the formatting and links are correct. The same process is being applied for the rest of the INAV versions until the docs have been fully migrated.

Oh I misunderstood that. I bet I can find a way to mostly automate it. I just wrote code that transforms JavaScript into INAV logic conditions - with full error checking and all. I imagine this wouldn't be too much more difficult. :)

[sensei-hacker]

I merged the PR on https://github.com/iNavFlight/iNavFlight.github.io

What else needs to be done to make it look like the draft here?:

https://www.spiffygoose.com/inavdocs/

[robotgoat]

Hosting the website should be pretty straightforward with Github pages. I submitted a new PR that changes the URLs to match that of inavflight.github.io's repository.

The remaining things to do is for that repository are:

• Activate Github pages and set "Build and Deployment" to Github Actions.
• In that same section in the settings, Github should automatically generate the URL https://inavflight.github.io/ where the built Docusaurus site is now hosted.
• Because the repo's main branch is called "master", that will also have to be changed in .github/workflows/deploy.yml. On line 6, simply change the branch name from main to master.

I currently see that https://inavflight.github.io/ shows only the readme, so once Github pages is setup, the full site should be shown.

The last thing to do is to change the DNS settings in the hosting provider's settings to point the inavflight.com domain to the Github pages. I'm not sure how that is all set up on your end though.