Update documentation for Harvest Widget release.

[adunkman]

@katierose4 @pusewicz /cc @dannyw if you’re interested.

This updates our documentation to be in-line with what the marketing site will be shortly.

The diff is pretty impossible to see what is going on, so I suggest browsing the tree on GitHub to see what the files will look like.

We started with writing the Harvest Widget and Harvest Button pages from scratch (since much of the old documentation applied to only one of the forms of integration) which makes the base README much simpler.

I anticipate that this won’t be the starting page for people looking at writing an integration — I anticipate that they will hit our marketing site first. I also just added that link as the URL to the project, so it now appears immediately at the top of the page:

[adunkman]

Also included in this PR is 16084d9, which removes the examples/ tree entirely — I didn’t see it existed until today, and it didn’t work. :whistles:

On the subject of examples not working, I’ve already copy-pasted these examples into bare HTML to confirm that they do, in fact, work — but feel free to double-check me if you’re concerned about it.

[adunkman]

Oh yes — and one more thing — for those unfamiliar with the changes (those outside Harvest) the Harvest Button is what you’re already familiar with — it’s just a documentation and naming update. The Harvest Widget is the new stuff.

[katierose4]

Thanks @adunkman @pusewicz. This is simple to follow.

The original README had some more business/product thoughts from an "advisory" perspective for partners. Granted some of this content is going to be moved to the new marketing page, I don't want to completely lose all of it. Until I figure out what content is going to go on marketing site vs. stay in GitHub, I'll just keep a copy of the text since I don't see it in this new version?

And the only commentary that I found confusing was the below line. I read this as, if a user hasn't tracked time, we try to suggest a Project or Task. I think that's misleading because we don't try to populate a Project and Task if you haven't tracked any time yet. Maybe if you explain what you mean by this, we can work towards making it more clear. Thanks for cleaning house on all these docs!

Harvest will take the information you provide about the item the user is tracking time against to suggest a Harvest Project and Task that we think the user is most likely to use. You cannot set the Harvest Project and Task shown by default explicitly.

[pusewicz]

Looks good! :+1:

[adunkman]

I'll just keep a copy of the text since I don't see it in this new version?

@katierose4 it’s in git history forever — no need to fear of it being lost. :) Here’s a permalink to the current version of all the documentation before this is merged.

[adunkman]

Harvest will take the information you provide about the item the user is tracking time against to suggest a Harvest Project and Task that we think the user is most likely to use. You cannot set the Harvest Project and Task shown by default explicitly.

I think that's misleading because we don't try to populate a Project and Task if you haven't tracked any time yet. Maybe if you explain what you mean by this, we can work towards making it more clear.

We do sometimes though — if someone in the company has used the “Create Project” link from within the time tracking form. I tried not to go too deep into details here, because I think it behaves roughly as you’d expect, and it can get really easy to get caught up in all the nuances of the details of how it works. Here’s the complete tree of how the suggestion works (taken from Trello):

1. My Project/Task: If the current user has tracked time to this external project and external task combination before, their last-used Harvest project and task should be used.
2. My Project: If the current user has tracked time to this external project before but not this external task, their last-used Harvest project should be used for the external project. Their last-used Harvest task should also be suggested.
3. Company Project/Task: If the current user has not tracked time to this external project before but another user at the company has tracked time to this external project and external task combination, the company’s last-used Harvest project and Harvest task should be suggested for this external project and external task combination.
4. Company Project: If the current user has not tracked time to this external project before but another user in the company has tracked time to this external project (but a different external task), the company’s last used Harvest project should be suggested for this external project. The company’s last used Harvest task should also be suggested.
5. No Time Tracked: If no user at the company has ever tracked time to this external project before but a project was created with the “Create Project” link in the Platform dialog for this external project, this Harvest project should be suggested. No Harvest task suggestion should be made — it should default to the first available task.
6. None: If no user at the company has ever tracked time to this external project before and no project was created with the “Create Project” link, then no Harvest project should be suggested — it should default to the first available project. Additionally, no Harvest task suggestion should be made — it should default to the first available task.

Additionally, after the above rules are applied:

1. If the suggested Harvest task is not available on the suggested Harvest project, no task suggestion should be made — it should default to the first available task.
2. If the suggested Harvest project is not available, no project suggestion should be made — it should default to the first available project.

I don’t think it’s valuable to go into that level of detail here — but maybe we can adjust the wording a bit to make it more clear. Here’s the full text of the summary I wrote:

Harvest will take the information you provide about the item the user is tracking time against to suggest a Harvest Project and Task that we think the user is most likely to use. You cannot set the Harvest Project and Task shown by default explicitly.

The Harvest Project and Task suggested is based on what time has already been tracked to this item in your application. If no time has been tracked to this item yet, then the suggestion is based off the group that the item is a part of in your application. If the group also has no time tracked, a Harvest Project that was created from the time tracking form will be considered.

[dannyw]

Just looked through the docs and they are wonderful and easy to follow. Great stuff!

Minor suggestions:

• For the "Harvest Widget" screenshot, I think things would look just a little sweeter if we have a simple 1px border around it. It otherwise looks like those form elements are just floating there.
• The links "Try it now..." feels like I'm going to be able to get a taste of how the integration works, and not so much about how to implement it. Some other copy like "Get started..." feels more appropriate.
• Should we include a little section under each type to explain when it's best to use it? For example, for Harvest Button, we could say something like "Ideal for: attaching timers to a list, adding time tracking while utilizing minimal real estate"

[adunkman]

For the "Harvest Widget" screenshot, I think things would look just a little sweeter if we have a simple 1px border around it. It otherwise looks like those form elements are just floating there.

Deal! :icecream:

The links "Try it now..." feels like I'm going to be able to get a taste of how the integration works, and not so much about how to implement it. Some other copy like "Get started..." feels more appropriate.

I had a bit of that feeling too. It felt almost like I should end up at a demo page, rather than documentation. I’ll go with “Get started!” to merge in @pusewicz’s feedback above.

Should we include a little section under each type to explain when it's best to use it? For example, for Harvest Button, we could say something like "Ideal for: attaching timers to a list, adding time tracking while utilizing minimal real estate"

I’ve been leaning on the “less is more” philosophy pretty hardcore, as you can probably tell by how much shorter these docs are from the last time. I think adding the screenshots to the page helped a lot with explaining what each of the integrations was, so i basically deleted all the descriptions.

Ideal for: attaching timers to a list, adding time tracking while utilizing minimal real estate

Perhaps that kind of thing is best suited for the marketing page? It seems like it’s selling a particular feature of the integration, rather than explaining what it is and how to use it.

[adunkman]

Just waiting on the code change to Harvestapp now (that drops the external_ prefixes); after that I think this is good to go.

[adunkman]

Just waiting on the code change to Harvestapp now (that drops the external_ prefixes); after that I think this is good to go.

Actually, that was a pain in the butt. I went down this path and it gets reeeeally ugly really fast in Harvestapp. I don’t think my displeasure over having external_ there is worth the pain of removing it. Going to revert the documentation change and roll with this as-is.

[adunkman]

Alright, we’re about to change the message format, but we can do that in a follow-up PR. This is better than what we have, so I’m going to :boat: and get on with life!