[Docs] Reorganize folders and sidebar in Docs

[Juulz]

Issue Type

Documentation Improvement

Description

Looking for input on reorganizing the Docs sidebar and folders. (Contributing not to be changed)

In small PRs, sections will get fixed/added and this will also fix #6188

Adding a Quick Start Guide will be part of the project that will fix #6190

Screenshots of sidebar:

Documentation URL

No response

Documentation Category

No response

Expected/Desired Content

No response

Screenshots or Examples

See above.

[Juulz]

Here's what I wrote on the netlify-fail PR:

This is a revamped outline of what I think the sidebar of Docs should look like.
In my local files, I have moved most of the files to their respective sidebar folder locations, including experimental features. The docs are currently located kinda all over the place.

To make experimental feature docs easier in the future, IMO, experimental feature docs should go to their respective end-place in the sidebar and be put in their final folder when introduced. A ToC of experimental features gets added to the experimental index that lives in the settings folder (this is not done yet).

The changes will come in small PRs as they get completed.

What say you?

[bpaulien]

It looks like a good, logical layout. Kinda stepping people through in the order they need to set up stuff to get it up and running in a logical order. First glance over looks good.

[StephenBrown2]

I wonder if there could be a superscript ^(exp) (or without parens: ^exp) on pages for experimental features while they're experiemental, now that they're getting mixed in with the rest of the docs?

I noticed a bit of duplication in the proposed outline. While I'm not against some duplication for ease of use, I am more in favor of one place to find something, which also means only one place to update.

For example, "Tracking Budget" has two pages: one top level, one under Budgeting. Since it's not the recommended path, should we remove the top-level page, or just have the top level link to the other?

Under "Quick Start Guide", I realize it's not done yet, but I'm not sure if the subpages will be just links or brief summaries of their respective pages elsewhere in the docs (-> Link, > Nested):

• "Install Actual" -> "Installation & Configuration"
• "Add Accounts" -> "Adding Accounts" > "Add Accounts"
• "Add Categories" -> "Budgeting" > "Categories"
• "Add Transactions" -> "Transactions"
• "Reconcile All Accounts" should maybe be named "Reconciling Accounts", -> "Adding Accounts" > "Reconciliation"
• "Starting Fresh" -> "Budgeting" > "Restarting Your Budget"
• "Starting a New Month" should go before "Starting Fresh", Should have a page under Budgeting to link to

The top level "Adding Accounts" should just be "Accounts", to align with top level "Transactions", and not have three places where "Add(ing) Accounts" is listed

Under Accounts:

• "Accounts" > "Credit Cards":
  • I think we should put "Paying in Full" before "Carrying Debt", again favoring the recommended path first
• I don't think the full title "Strategies for Handling Joint Accounts" in the sidebar, just "Joint Accounts" would do, unless it's required to use the full title from the page in the sidebar.

Under Transactions, I would order the items like this:

• Payees
• Filtering Transactions
• Bulk Actions
• Split Transactions
• Transfers
• Duplicate Transactions
• Tags (Could be moved after Payees, as well)
• Rules
  • ...

Under Budgeting:

• "Budget Templates" should probably go before "End of Month Cleanup"
• "Restarting Your Budget" is the same as "Starting Fresh", yes?
• Again I would move "Tracking Budget" to the end of the list

Under Reports:

• "Excel Formula Mode..." should be renamed "Formula cards" and split from "Rule formulas", which would then go under "Transactions" > "Rules". An unfortunate side effect of putting the experimental features into the mix of the rest, IMO.

Under "Utilities & Troubleshooting"

• "Frequently Asked Questions" should be a tippy-top level item. I would put it right after "Release Notes" personally. It's in a good spot in the current outline, under "Help & Support".
• "Restarting Your budget" is duplicated here, should stay only under "Budgeting"
• "Backups" should be it's own second-level item, over both "Backing up" and "Restoring"
• "Settings" seems like it should go under "Installation & configuration" though I realize that is more focused on the server side.
• "Troubleshooting Server Configuration Issues" could also be shortened to "Server Configuration Issues" since it's under "Troubleshooting" already

[Juulz]

The Quick Start Guide fixes Issue #6190 - Create an opinionated guide. It will not just be links to other docs but a fresh start for new users giving only desktop or pikapods as install choices.

I ordered the transaction section in the order that new users actually use them and ask questions about them. Convince me! 😀 I have only used "Bulk Actions" once. I use split transactions, merging dupes, filters and schedules almost daily. As long as things are findable and in an expected place (or two).

The sidebar currently uses the title from the doc. That can get changed - some of them are very wordy.

Any doc that is in two places (looking at you tracking budget) will have a main home and the secondary spot will not be part of the next/previous flow at the page bottom.

Starting Fresh is not the same as restarting. 😁

I have no problem putting a page in two places! I would rather they be found than hidden.

The superscript idea for experimental features is a good one. I'll test that. My thought was that the index page for experimental features would explain them generally as now and have a current list of links to docs and feedback. Moving them out of experimental should be much easier as the docs will need a bit of editing, but the structure will be in place.

CC Paying in Full does come first in the sidebar now and that will not change.

I thought that Backup & Restore was a collapsed item. I guess it broke out of it's pen. LOL

Because I used current pages, some of the names are not really descriptive of the text. Some long docs will need to get split out.

The Quick Start Guide will hopefully never have to be referenced again - it is not be meant to be a repository of info that is not described in detail elsewhere. It's just for onboarding. If it links to other pages, they will open a new window so the new user doesn't lose their place in the Guide.

This is a really big project as there are LOTS of broken links from moving things into their correct folders. I am hoping when it's done, we will be able to have docusaurus auto-generate the sidebar so it won't have to be maintained anymore.

[StephenBrown2]

I ordered the transaction section in the order that new users actually use them and ask questions about them. Convince me! 😀 I have only used "Bulk Actions" once. I use split transactions, merging dupes, filters and schedules almost daily. As long as things are findable and in an expected place (or two).

Fair point, I ordered them as I would consider them, though admittedly Bulk Actions could be moved down, I think it would be helpful to surface earlier users as it would help answer some questions I've seen come up.

Starting Fresh is not the same as restarting. 😁

https://actualbudget.org/docs/advanced/restart

Restarting Your Budget

If you've fallen behind on your budgeting and want to start fresh without starting from scratch.

https://actualbudget.org/docs/getting-started/starting-fresh

Starting Fresh

For most users it's best to start fresh with a blank file. ... without migrating from a previous budget software export.

Also fair, though they are very close, and even use the same term "start fresh", so I would recommend differentiating them more, but I recognize that's not what this reorg is for.

I have no problem putting a page in two places! I would rather they be found than hidden.

Me neither! But they should be a link to the same content, so that maintenance is easier and one doesn't get out of sync with the other, unless one is a summary pointing to the other, like with the new QSG.

I am hoping when it's done, we will be able to have docusaurus auto-generate the sidebar so it won't have to be maintained anymore.

That would be great, but I don't know how feasible it would be. :-)

[StephenBrown2]

Cursor was able to do the experimental notation in not much code, details over in the PR: #7472 (comment)

[Juulz]

Cursor was able to do the experimental notation in not much code, details over in the PR: https://github.com/actualbudget/actual/pull/7472/commits#issuecomment-4238089404

Thanks a bunch! Visiting out of town for a couple of days. I'll get back to docs later this week.