n8n-io / n8n-docs

Documentation for n8n, a fair-code licensed automation tool with a free community edition and powerful enterprise options. Build AI functionality into your workflows.
https://docs.n8n.io
Other
154 stars 295 forks source link

DOC-1010: Update X credentials to medium tier template #2340

Closed freakwriter closed 3 weeks ago

freakwriter commented 1 month ago

Summary of changes:

netlify[bot] commented 1 month ago

Deploy Preview for n8n-docs ready!

Name Link
Latest commit adb41897d851ff144bdec93c5579027527cb697d
Latest deploy log https://app.netlify.com/sites/n8n-docs/deploys/66c379c472f0b7000861ad7f
Deploy Preview https://deploy-preview-2340--n8n-docs.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions[bot] commented 1 month ago

Overall readability score: 42.77 (🟢 +0)

File Readability
twitter.md 61.53 (🔴 -4.47)
View detailed metrics 🟢 - Shows an _increase_ in readability 🔴 - Shows a _decrease_ in readability File | Readability | FRE | GF | ARI | CLI | DCRS --- | --- | --- | --- | --- | --- | --- [twitter.md](https://github.com/n8n-io/n8n-docs/blob/adb41897d851ff144bdec93c5579027527cb697d/docs/integrations/builtin/credentials/twitter.md "docs/integrations/builtin/credentials/twitter.md") | 61.53 | 40.24 | 8.03 | 12.4 | 12.93 | 6.78   | 🔴 -4.47 | 🔴 -0.61 | 🔴 -0.72 | 🔴 -0.6 | 🔴 -0.35 | 🔴 -0.55 Averages:   | Readability | FRE | GF | ARI | CLI | DCRS --- | --- | --- | --- | --- | --- | --- Average | 42.77 | 34.59 | 11.71 | 14.94 | 14.41 | 8.57   | 🟢 +0 | 🟢 +0 | 🟢 +0 | 🟢 +0 | 🟢 +0 | 🟢 +0
View metric targets Metric | Range | Ideal score --- | --- | --- Flesch Reading Ease | 100 (very easy read) to 0 (extremely difficult read) | 60 Gunning Fog | 6 (very easy read) to 17 (extremely difficult read) | 8 or less Auto. Read. Index | 6 (very easy read) to 14 (extremely difficult read) | 8 or less Coleman Liau Index | 6 (very easy read) to 17 (extremely difficult read) | 8 or less Dale-Chall Readability | 4.9 (very easy read) to 9.9 (extremely difficult read) | 6.9 or less
freakwriter commented 1 month ago

@nik8n and @ayatnkw This review might be a little more involved since X/Twitter stuff is a bit odd since we still have the old auth method from older versions that folks may need.

Whether to document the method still is a grey area in our existing docs--when I asked Debs about when we officially sunset docs on things for old versions, it seemed to be a judgment call based on two factors:

If it wasn't discoverable in the UI, and it applied to version 0.xxx of n8n, we generally removed the docs entirely. But if it was still in the UI and/or in version 1.xxx of n8n, we kept it.

This credential is a weird edge case. The OAuth credential ties to OAuth1.0a, which is only used with V1 of the X node. We released the updated version of that node in 0.236.0.

But you can still find that credential if you search from the Credentials interface (rather than from opening it within the X node itself). Jon and I had a brief convo about it in Linear.

So for now I left it in but I moved it below the other auth method and tried to add some warnings about using it.

All of that said: I would really LIKE to remove this old auth method from the docs entirely, since it's not relevant for a lot of our current users. But because it's a bit of an edge case, that feels like a decision we should make collectively.

So: what do you think?

ayatnkw commented 1 month ago

@freakwriter @nik8n If we're deprecating the OAuth eventually, I think we can remove the old auth method from the current docs. I think having more content on the page just makes it more confusing for new users. (But if we do keep it, I might change the warning note to Deprecation warning instead of Recommended usage ...)

One question — in the UI we refer to the node as X (formerly Twitter), maybe we should include the (formerly Twitter) part to make it more searchable? (Noticed other platforms and softwares also do this)

freakwriter commented 3 weeks ago

@ayatnkw thanks, that was all good feedback and I've incorporated all of it in some fashion.