Roadmap to Documentation for Tauri 2.0

[lorenzolewis]

As we're prepping for Tauri 2.0 we're also switching over our documentation platform. Now is an awesome time to get involved in Tauri documentation!

Check the milestone for the overall status to having 2.0 docs ready: https://github.com/tauri-apps/tauri-docs/milestone/4

Writing Contributions

Below is the outline for the new docs. If there is no name next to one feel free to claim it so we can mark your name and then open a PR so that we can start crafting the doc together.

• Quick Start
  • What is Tauri? @lorenzolewis
  • Prerequisites
  • Create a Project
    • Using CTA
    • Manually using Tauri CLI
    • Add mobile to an existing project
    • ...Frontend framework-specific guides
  • Upgrade and Migration
    • From Tauri v1 @lucasfernog feat: add upgrade guide #1340
    • Electron to Tauri
    • ...any other framework suggestions?
  • Core Concepts
    • SPAs, SSGs, etc.
    • ...what else?
  • Plugins @lucasfernog
    • What is a Plugin? @lucasfernog
    • Developing a Plugin @lucasfernog
    • List of plugins (This page should cover that: https://beta.tauri.app/features/) @lucasfernog
  • Troubleshooting
• Guides
  • Write Develop Guide #1468
  • Write Debug Guide #1469
  • Write Test Guide #1470
  • Write Build & Distribute Guide(s) #1471
• Features & Recipes (all listed under https://beta.tauri.app/2/guide/list)
  • Create Authenticator guide #1473
  • Create Autostart guide #1474
  • Create Clipboard guide #1475
  • Create Command Line Interface (CLI) guide #1476
  • Create Dialog guide #1477
  • Create File System guide #1478
  • Create Global Shortcut guide #1479
  • Create HTTP Client guide #1480
  • Create Localhost guide #1481
  • Create Logging guide #1482
  • Revise Notification guide #1483
  • Create OS Information guide #1484
  • Create Persisted Scope guide #1485
  • Create Positioner guide #1486
  • Create Process guide #1487
  • Create Shell guide #1488
  • Create Single Instance guide #1489
  • Create SQL guide #1490
  • Create Store guide #1491
  • Create Stronghold guide #1492
  • Create Updater guide #1493
  • Create Upload guide #1494
  • Create Websocket guide #1495
  • Create Window Customization guide #1496
  • Create Window State guide #1497
  • Write Deep Link guide #1547
  • Write Barcode Scanner guide #1548
  • Create NFC guide #1949
  • Create Biometric guide #1948
• References
  • Create Tauri 2.0 CLI Reference #1363
  • Fix Tauri Config Generator #1472

Technical Contributions

• Upstream contributions to Starlight to allow overriding components (footers, etc.)
• Create a plugin index page for the reference section
• Create DevContainer Configuration for Repo #1362
• Dynamic OG images (depends on Ability to customise Starlight’s components withastro/starlight#415). Reference: https://github.com/JonasKruckenberg/JonasKruckenberg/blob/main/src/pages/social-image/%5B...path%5D.png.ts feat: Dynamic og image #1344 #1616

Translations (i18n)

Check out the https://github.com/tauri-apps/tauri-docs/blob/next/.github/TRANSLATING.md guide

Transition Checklist

Here's what we need to remember to do as part of the transition over:

• Remove beta and next branches and respective search indexes
• Turn off Crowdin and remove any references, redirect them back to the repo
• Add CI to deploy the next/latest version of documentation when upstream dev changes for live previews (and to make sure nothing upstream causes issues)

Upstream Issues

External

• Fix issue with nested <Tabs> components withastro/starlight#473: Noticed some non-nested tabs are also broken, hoping this fixes it when released
• JavaScript not being bundled in production build for components withastro/astro#8018: Tabs not working when using components with imports on the same page
• Copy button for Code Blocks withastro/starlight#461
• Search index based on headers Pagefind/pagefind#215: Surface headings in search results
• Add segments of words with punctuation to index Pagefind/pagefind#225: Better search results for more code-like things
• Ability to customise Starlight’s components withastro/starlight#415: Support overriding translated locale pages to highlight if translates are out of date
• [next] Items in tables are not linkable typedoc2md/typedoc-plugin-markdown#463
• Add support for synced tabs withastro/starlight#640
• v8.0.0 always returns *.*.*.0 instead of actual IP sindresorhus/internal-ip#48

Internal

• Tauri CLI 2.0 DX Improvements tauri#7572
• [feat] 2.0: Add plugin to lib.rs with tauri plugin add tauri#7696
• refactor(cli): rename plugin add command to add tauri#7744
• [feat] Add CLI option to tauri plugin init to enable/disable iOS/Android projects tauri#7749
• https://github.com/tauri-apps/tauri/tree/refactor/jsdoc Not planned

Open Items

• Build out NixOS instructions and other Linux distros (do we want to allow any and all Linux distros into the docs? Can we support that effectively?)
• Does the version number in the code block below change over time? Do we need to make a note on that?
  

  tauri-docs/src/content/docs/2/guide/prerequisites/index.mdx

  Lines 250 to 253 in c46d1f2

  	```sh
  	export ANDROID_HOME="$HOME/Library/Android/sdk"
  	export NDK_HOME="$ANDROID_HOME/ndk/25.0.8775105"
  	```

  
  

  tauri-docs/src/content/docs/2/guide/prerequisites/index.mdx

  Lines 260 to 263 in c46d1f2

  	```ps
  	[System.Environment]::SetEnvironmentVariable("ANDROID_HOME", "$env:LocalAppData\Android\Sdk", "User")
  	[System.Environment]::SetEnvironmentVariable("NDK_HOME", "$env:LocalAppData\Android\Sdk\ndk\25.0.8775105", "User")
  	```

• Can we optimise the Android steps:
  

  tauri-docs/src/content/docs/2/guide/prerequisites/index.mdx

  Lines 208 to 210 in c46d1f2

  	2. Set the `JAVA_HOME` environment variable:
  	{/* TODO: Can this be done in the 4th step? */}

• Build plugin dev CLI section
  

  tauri-docs/src/content/docs/2/guide/plugins/index.mdx

  Line 6 in 2d970c9

  {/* TODO: Add a CLI section */}

[clearlysid]

Core Concepts
SPAs, SSGs, etc.

Happy to help with this piece 🙌

[OscarArranz]

I'd be happy to help with the NextJS specific guides!

[simonhyll]

@OscarArranz Awesome! I've started on some framework specific guides in #1405, you can check out the preview here
https://deploy-preview-1405--tauri-docs-starlight.netlify.app/2/guide/framework/nextjs/

@lorenzolewis feel free to correct me on any of this:

Note that we for 2.0 want to keep the framework specific stuff as limited as possible, preferably the information on that one page should be all you need. So no super long articles about the frameworks and not a lot of code samples beyond getting set up, because once you're set up it's up to the framework in question to instruct you on how to e.g. import and run javascript functions. The docs in v1 are quite overkill for just letting people know what they need to be aware of about the framework and most of the contents in v1 is duplicated across the frameworks. We want to avoid such duplication, have the framework setups short and sweet, then focus on actual meaningful framework agnostic docs.

I'm no expert on Next.js and most of the content on the Next.js page is just copied over from the next branch, so would love to hear from you on whether the contents are correct and if there are any other gotchas that should be added to the checklist 🙂

There's more wiggle room for writing blog posts if you want to do something like a deep dive into things like best practises for hooking up Next.js with Tauri, so there's room on the website for the content you might want to write, just maybe not on those specific pages 🙂

[lorenzolewis]

Core Concepts
SPAs, SSGs, etc.

Happy to help with this piece 🙌

@clearlysid amazing! I'll put a few points here from @simonhyll that would be good to cover for SPA, SSG, SSR. Feel free to open a draft PR with a first stab and then I'll tag your name on it above.

• SPA: What is it? Why is it nice to have?
• SSG: What is it? Why is it the only Tauri supports?
• SSR: What is it? Why does Tauri NOT support it?

For docs try to keep any non-Tauri concepts fairly high-level (what is SPA, SSG, SSR, etc.) and link out where relevant for the reader to find more info. The docs should really focus as much as possible on Tauri-specific ideas.

If you have any questions then feel free to hop on to our Discord and ping us in the #docs channel there 🎉

CC @FabianLars because I know you've fought the dragon a few times on this in support, so I'm sure any advice would be appreciated.

[lorenzolewis]

@OscarArranz +1 to everything @simonhyll said. We're currently churning through the first plugin-specific guide (#1379) to get it just right, and then maybe we could try to polish up #1405 and get it merged to make it easy for people to contribute to.

And like I mentioned on Discord, we'll open up translations ASAP once we get a few more things across the finish line. If you'd like to have a peek feel free to take a look at https://github.com/tauri-apps/tauri-docs/blob/next/.github/TRANSLATING.md. We've tested that whole flow a few times but any feedback would be greatly appreciated!

Happy to have you join us 🥳

[OscarArranz]

@lorenzolewis Definitely hit me up when you need to start translating and I'll make sure to work on Spanish translations.

As for writing English docs, I'm realizing maybe I'd need to mess around with the latest version of Tauri as I'm currently using 1.4. If you've got any guidance on how to get familiar with the latest version and it's code it'd be amazing.

I'm really excited to help with anything I can but I also feel a bit intimidated by the size of the project 😅

[lorenzolewis]

@OscarArranz the sections to get someone up and running are what we're going to laser-focus on next week starting Tuesday. We'll probably discussion in #docs on Discord so I'll give you a shout there if you're interested in joining the discussion.

The prerequisite page should be all ready and functional for 2.0, so maybe give that a walk through and see if it gets you setup for success.

[clearlysid]

Sorry, Github doesn't notify me well enough 🥲. Would love to continue in Discord but I don't seem to be able to send messages in #docs.

Yes,I'll take a first pass and draft a PR. Is there a timeline we're looking at? I'll be able to get to this over the coming weekend.

[lorenzolewis]

@clearlysid give me a mention in #general on Discord (@lorenzolewis over there) and I can make sure to get you all set up there.

There aren't any real strict timelines per se, but I'm personally going to be out on vacation for about a month starting Sept 10, so it would be amazing to get a few rounds of feedback with anything you have to share and then the rest of the team could help to push it through from there

[probablykasper]

Note about window customization, there's currently a guide for custom titlebars which implements window controls in HTML/CSS. For macOS this is flawed/bad behavior as users lose standard features. imo users should be warned about this, and potentially recommend transparent title bar + custom window background color like this

[lorenzolewis]

Thanks @probablykasper , I added a stub for a window customisation guide in #1455 and included a reference to your comment so we can be sure to incorporate it 💪

[clearlysid]

#1456 is now up! I'll continue discussions, feedback and writing more on there directly.