General editing pass over most of the docs pages #462

bcantoni · 2022-02-01T02:49:41Z

I reviewed everything under the Docs section to make several types of minor edits:

updated links
trimmed some whitespace in particular for sample code blocks
replaced Extension Gallery with Tableau Exchange
updated some instructions to reflect current versions of Tableau
minor text edits

I reviewed everything under the Docs section to make several types of minor edits: - updated links - trimmed some whitespace in particular for sample code blocks - replaced Extension Gallery with Tableau Exchange - updated some instructions to reflect current versions of Tableau - minor text edits

seanmakesgames · 2022-02-01T21:47:36Z

README.md

-
 ## Submissions
-We would love submissions to either the Docs or Sample code! To contribute, first sign our CLA that can be found [here](https://tableau.github.io/contributing.html).  To submit a contribution, please fork the repository then submit a pull request to the `submissions` branch.
+We would love submissions to either the Docs or Sample code! To contribute, first sign our CLA that can be found [here](https://tableau.github.io/contributing.html).  To submit a contribution, please fork the repository then submit a pull request to the `dev` branch.


This should be main branch. dev branch is for internal development purposes. (this could change in the future, but is correct for now)

Oops good catch!

seanmakesgames · 2022-02-01T21:49:25Z

docs/trex_api_about.md

-    unregisterEventHandlerFunction = worksheet.addEventListener('mark-selection-changed', myfunctionHandleSelectionEvent);
+```javascript
+// Add an event listener for the selection changed event on this sheet.
+unregisterEventHandlerFunction = worksheet.addEventListener('mark-selection-changed', myfunctionHandleSelectionEvent);


put a let in front of this. (I think)

or a const!

seanmakesgames · 2022-02-01T21:52:14Z

docs/trex_error_handling.md

 ## Handle extensions.ui dialog box errors

-For an example of how to handle an extension dialog box error, see the [UINamepace](https://github.com/tableau/extensions-api/tree/master/Samples/UINamepace?=target="_blank") sample. The sample shows how you could handle the error condition that occurs if a user dismisses a modal dialog box (`DialogClosedByUser`). In this extension, the user is expected to click the **Start Auto Refresh** button, which saves the configuration settings and closes the dialog box, by calling the `tableau.extensions.ui.closeDialog()` method with the return payload. If a user clicks the dialog box control (the **X** in the upper-right corner) instead, the error occurs. The following snippet illustrates how you could handle this error: 
+For an example of how to handle an extension dialog box error, see the [UINameSpace](https://github.com/tableau/extensions-api/tree/main/Samples/UINamespace) sample. The sample shows how you could handle the error condition that occurs if a user dismisses a modal dialog box (`DialogClosedByUser`). In this extension, the user is expected to click the **Start Auto Refresh** button, which saves the configuration settings and closes the dialog box, by calling the `tableau.extensions.ui.closeDialog()` method with the return payload. If a user clicks the dialog box control (the **X** in the upper-right corner) instead, the error occurs. The following snippet illustrates how you could handle this error:


remove caps on nameSpace

The capitalization just reflects the name of the path/folder on GitHub. The folder is "UINamespace" but the names of the files are uiNamespace Should we rename the folder?

I think we'll be consistent if we refer to it by folder name, in this case UINamespace (previously we had UINameSpace but I'm fixing it per Sean suggestion). I don't think we need to rename the folder for this.

seanmakesgames · 2022-02-01T21:55:37Z

docs/trex_getstarted.md

 This section will take you through the process of setting up your environment to use one of the sample dashboard extensions. Using one of the sample extensions is a great way to learn and great way to get started developing your own extensions. In this section, you will start a simple web server on your computer to host the sample. You can use the same process for hosting the extension when you start developing your own.

-<div class="alert alert-info"><p><b>Note</b> If you are looking for information about how to add an extension to a dashboard in Tableau, see <a href="https://onlinehelp.tableau.com/current/pro/desktop/en-us/dashboard_extensions.htm" target="_blank" ref="noopener">Use Dashboard Extensions</a>. If you are looking for extensions that you can use, see the <a href="https://extensiongallery.tableau.com/" target="_blank" ref="noopener">Tableau Extension Gallery</a>.</p>
+<div class="alert alert-info"><p><b>Note</b> If you are looking for information about how to add an extension to a dashboard in Tableau, see <a href="https://onlinehelp.tableau.com/current/pro/desktop/en-us/dashboard_extensions.htm" target="_blank" ref="noopener">Use Dashboard Extensions</a>. If you are looking for extensions that you can use, see the <a href="https://exchange.tableau.com/" target="_blank" ref="noopener">Tableau Exchange</a> (formerly, Tableau Extension Gallery).</p>


Do we need this 'formerly' note in there?

I put this here and one other place just to have some mention of extension gallery, for those who might know it by the former name.

Yeah. ~~I think we can drop the formerly. It will soon be forgotten.~~ Can't hurt during the transition.

fixed (removed those refs)

docs/trex_getstarted.md

seanmakesgames · 2022-02-01T21:59:45Z

docs/trex_sandbox_publish.md

-Once accepted, Tableau will publish your extension and your extension will be available in the [Extensions Gallery](https://extensiongallery.tableau.com/){:target="_blank"}{:ref="noopener"}.  
-

+For information about what goes in the form, see [Submitting your Extension to the Tableau Exchange]({{site.baseurl}}/docs/ux_extension_gallery.html){:target="_blank"}.


can this be a relative path?

Yes but I think the convention Dave has is when pointing to the "UX" pages they open in a new tab, similar to #462 (comment)

Our GitHub Pages are set up to use the baseurl setting in the _config.yml. It allows us to build and view it locally with Jekyll and it works on GitHub. We should leave the path alone.

Building with the baseurl like this is needed when we have a target=blank like this one. In other places with normal links we can just point to the md file.

Please don't change the links to the .md file. It works on GitHub with the Jekyll, but there have been times where I've built the Help locally and hosted it on other staging sites. And it was failing there. I guess, my comment it if it ain't broke don't change it. At some point, I'd like to move all the Help content to GitLab (like the Embedding API). That would improve automation and speed up publishing.

seanmakesgames · 2022-02-01T22:00:08Z

docs/trex_sandbox_publish.md


+For information about what goes in the form, see [Submitting your Extension to the Tableau Exchange]({{site.baseurl}}/docs/ux_extension_gallery.html){:target="_blank"}.

+Our developers from the Developer Platform team at Tableau will let you know the next steps including legal agreements after you submit your information. If you have any questions about the Exchange please send them to [extensiongallery@tableau.com](mailto:extensiongallery@tableau.com){:target="_blank"}{:ref="noopener"}.


is this the correct email still?

Yes this is in my questions doc where I'm confirming with Blake.

Confirmed this is correct.

seanmakesgames · 2022-02-01T22:00:51Z

docs/trex_sandbox_test.md

 * **Network Enabled Extensions** - can access resources and applications outside of Tableau. Supported in Tableau 2018.2 and later.

-* **Sandboxed Extensions** - run in a Tableau hosted environment and cannot make network calls. Supported in Tableau 2019.4 and later. Available for testing with Tableau 2019.3.
+* **Sandboxed Extensions** - run in a Tableau hosted environment and cannot make network calls. Supported in Tableau 2019.4 and later.


can we / do we remove this after 2019.4 is no longer in the support window?

I'll add that to my future notes list. In this pass I left these mostly alone.

We no longer support 2019.4 (see supported versions below)
https://www.tableau.com/support/services

So in the next pass, we'll remove any comments about these versions?

I understand that - what I meant was I didn't want to tackle that here in this editing pass. There are a lot of versions mentioned everywhere so we'll need to figure out the strategy for where/when to update them.

I included this on my "future doc improvements" list in #464

I agree. It's kind of a mess. As new features have been introduced or as other factors changed (looking at you Chrome and Qt), we've had to kind of layer the versions in.
I've had a work item to add a topic about versions and compatibility. That would probably help.

docs/ux_design.md

seanmakesgames · 2022-02-01T22:05:03Z

docs/ux_extension_gallery.md

 ## How to Submit your Extension

-After completing your extension, fill out the [Tableau Exchange Submission form](https://tabsoft.co/gallerysubmit){:target="_blank"}{:ref="noopener"} with your information and extension details. The extension name in the template needs to match the name you specified for your extension in the manifest file (`.trex`). The 280x280 pixel `.png` icon that you attach with your submission must look like the icon you included in your manifest file (they just have different dimensions). Our developers from the Developer Platform team at Tableau will let you know the next steps including legal agreements after you submit. If you have any questions about the Tableau Exchange please send them to [extensiongallery@tableau.com](extensiongallery@tableau.com){:target="_blank"}{:ref="noopener"}.
+After completing your extension, fill out the [Tableau Exchange Submission form](https://tabsoft.co/gallerysubmit){:target="_blank"}{:ref="noopener"} with your information and extension details. The extension name in the template needs to match the name you specified for your extension in the manifest file (`.trex`). The 280x280 pixel `.png` icon that you attach with your submission must look like the icon you included in your manifest file (they just have different dimensions). Our developers from the Developer Platform team at Tableau will let you know the next steps including legal agreements after you submit. If you have any questions about the Tableau Exchange please send them to [extensiongallery@tableau.com](mailto:extensiongallery@tableau.com){:target="_blank"}{:ref="noopener"}.


Is this email correct still?

Confirming but yes I believe so.

Confirmed this is correct.

d45 · 2022-02-01T22:17:26Z

_includes/docs_menu.html

        </li>
        <li>
-            <a href="{{ site.baseurl }}/docs/ux_design.html" target="_blank">Design Guidelines for Dashboard Extensions</a>
+            <a href="{{ site.baseurl }}/docs/ux_design.html">Design Guidelines for Dashboard Extensions</a>


@bcantoni - I put these in here so that the Design Guidelines (a separate guide with its own TOC) would popup in a new tab. That was the idea for the Design Guide and for the Dashboard Extensions API reference, which also has its own TOC. Can re-visit if it's not working.

Gotcha - I'll return them.

d45 · 2022-02-01T22:19:32Z

_includes/docs_menu.html

        </li>
        <li>
-            <a href="{{ site.baseurl }}/docs/trex_tableau_viz_ref.html" target="_blank">Tableau Viz Reference</a>
+            <a href="{{ site.baseurl }}/docs/trex_tableau_viz_ref.html">Tableau Viz Reference</a>


My mistake. The VizAPI isn't a separate doc set and so it shouldn't have the target="_blank"

d45 · 2022-02-02T00:37:03Z

_layouts/docs.html

            <h1>{{ page.title }}</h1>
            <div class="edit-container">
-                <a href="https://github.com/tableau/projectfrelard/edit/master/{{ page.path }}" class="edit-links"><span class="glyphicon glyphicon-pencil"></span> Edit this page</a>
+                <a href="https://github.com/tableau/extensions-api/edit/main/{{ page.path }}" class="edit-links"><span class="glyphicon glyphicon-pencil"></span> Edit this page</a>


@bcantoni Good catch! Project Frelard was the code name and the name of the repo when we were first launching.

Indeed - luckily GitHub does the right thing and handles with a redirect both the repo name and default branch name changes.

d45 · 2022-02-02T00:41:28Z

docs/Interaction_Guidelines/ux_build_test.md

 * [Community Forums](https://community.tableau.com/community/developers/extensions-api/overview)<br>Participate in a community of developers that are passionate about creating extensions.

-* [Extension Gallery (beta)](https://extensiongallery.tableau.com/)<br>Explore and use some of the extensions our partners have created.
+* [Tableau Exchange](https://exchange.tableau.com/)<br>Explore and use some of the extensions our partners have created.


Thanks for catching all these gallery references. I missed them completely when I updated references earlier.

d45 · 2022-02-02T00:45:57Z

docs/trex_api_about.md

 ## Registering and accessing dashboard extensions

-The dashboard extension is one type of extension in the Tableau extensions namespace (and it is accessed using `tableau.extensions`). To register the extension, you declare the type of extension in the manifest file (`.trex`). For more information about what goes in the file, see [Tableau Manifest File]({{site.baseurl}}\docs\index.html). 
+The dashboard extension is one type of extension in the Tableau extensions namespace (and it is accessed using `tableau.extensions`). To register the extension, you declare the type of extension in the manifest file (`.trex`). For more information about what goes in the file, see [Tableau Manifest File](./trex_manifest.md).


My mistake. The link when to the API reference page. The url should be {{site.baseurl}}\docs\trex_manifest.html

So the full link is:
[Tableau Manifest File]({{site.baseurl}}\docs\trex_manifest.html)

I think it's cleaner and perhaps more standard to just point to the relative .md file like this. These will resolve correctly when published but also when doing a local jekyll build.

d45 · 2022-02-02T00:51:18Z

docs/trex_create.md

+  - For `<icon>` you must use a Base64-encoded icon. To use the default icon, copy and paste the `<icon>` example here, or copy one of the manifest files (`.trex`) from the samples.
+  - Provide the `name` for your extension (`Hello Extensions!`). The manifest file can be localized, so provide the name (or names) in the appropriate `<text>` elements in the `<resources>` section.
+- After you have created the HTML and JavaScript files for your extension, you use this `.trex` file to add the extension to a Tableau dashboard. To do that, you drag the **Extension** object on to the dashboard. In the **Add an Extension** dialog box, click **Access Local Extensions** to locate and open the manifest file you just created.
+- For information about the manifest file and about adding version information, see the [Tableau Extension Manifest File](trex_manifest.md).


These are GitHub page, so the URL needs to be:
{{site.baseurl}}/docs/trex_manifest.html

Same as above - these relative links work directly by pointing to the .md file.

d45 · 2022-02-02T01:57:35Z

docs/trex_debugging.md

 The debugger will pause each time the first statement of a script runs, allowing you to debug the startup process.
-
-1. To get to your JavaScript code, click **Continue** several times. After your JavaScript is loaded, you can set a breakpoint in your startup code.
+4. To get to your JavaScript code, click **Continue** several times. After your JavaScript is loaded, you can set a breakpoint in your startup code.


fyi - In Markdown, if every step is numbered 1, they automatically get numbered in the correct order when the page is rendered into the GitHub Pages (HTML). That way you don't have to worry about things when you add or remove steps. I didn't know about this until someone showed me.

This is numbered 1.

This is numbered 1.

This is numbered 1.

Yep - my old habit is to number them so that people reading the text version of the file get a good version too. Here it's probably simpler to number as 1's because people are just reading the generated docs.

d45 · 2022-02-02T02:20:33Z

docs/trex_security.md

 assures your customers that their data is safe and that they are connecting to a trusted extension. Because the extension is using HTTPS, Tableau is also able to verify the identity of the server that hosts the extension, which prevents various malicious man-in-the-middle attacks that could occur if the extension were to use HTTP alone.  

-> Note: For development or internal use, you can run your extension on your local computer as `localhost` and you can use the HTTP protocol. See [Use HTTP and localhost for development or internal use](#use-http-and-localhost-for-development-or-internal-use).
+| Note: For development or internal use, you can run your extension on your local computer as `localhost` and you can use the HTTP protocol. See [Use HTTP and localhost for development or internal use](#use-http-and-localhost-for-development-or-internal-use).


This should be >. The Markdown for a block quote is a >, which is what we are using here. And it gets rendered as a vertical line.
It's not the best. It would look better if we used HTML "note" for it, but a that's not great either.

d45

@bcantoni Thanks for doing this edit pass and update!
I have some fixes to add after this PR gets resolved and merged.

bcantoni · 2022-02-02T06:20:07Z

@d45 I think this one got a little bit long and too ambitious, so I may just pull it back and let you do your changes instead. I'll try again with just fixing specific problems I first spotted and don't do as many formatting things.

d45 · 2022-02-02T16:39:37Z

@bcantoni Oh, OK. I'll go ahead with my bug fix for the Viz API (axis label). If it's OK with you, I'll correct the references to the Gallery that you identified. And also the broken links caused by projectfrelard references.

bcantoni · 2022-02-02T16:55:57Z

@d45 sounds good, I'll pass the ball to you. From my branch if you could pick up changes to these files that would be helpful:

README.md (fix branch name and combine redundant sections)
_includes/header.html (better header link to developer page)
docs/trex_api_about.md (line 27 link to tableau manifest file page)

seanmakesgames suggested changes Feb 1, 2022

View reviewed changes

d45 reviewed Feb 1, 2022

View reviewed changes

Address feedback comments

3a9c3c5

d45 reviewed Feb 2, 2022

View reviewed changes

Combine Submissions and Contributions section together

be94a40

d45 reviewed Feb 2, 2022

View reviewed changes

bcantoni mentioned this pull request Feb 2, 2022

Future documentation improvements #464

Open

d45 reviewed Feb 2, 2022

View reviewed changes

bcantoni closed this Feb 2, 2022

bcantoni deleted the 2022-02-update-docs branch September 11, 2023 17:52

		Once accepted, Tableau will publish your extension and your extension will be available in the [Extensions Gallery](https://extensiongallery.tableau.com/){:target="_blank"}{:ref="noopener"}.


		For information about what goes in the form, see [Submitting your Extension to the Tableau Exchange]({{site.baseurl}}/docs/ux_extension_gallery.html){:target="_blank"}.


		For information about what goes in the form, see [Submitting your Extension to the Tableau Exchange]({{site.baseurl}}/docs/ux_extension_gallery.html){:target="_blank"}.

		Our developers from the Developer Platform team at Tableau will let you know the next steps including legal agreements after you submit your information. If you have any questions about the Exchange please send them to [extensiongallery@tableau.com](mailto:extensiongallery@tableau.com){:target="_blank"}{:ref="noopener"}.

General editing pass over most of the docs pages #462

General editing pass over most of the docs pages #462

Uh oh!

Conversation

bcantoni commented Feb 1, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d45 Feb 1, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d45 Feb 1, 2022 •

edited

Loading

d45 Feb 2, 2022 •

edited

Loading