With all due respect, Box documentation is horrible

Hi ,

Thanks for your feedback and sorry to hear that the documentation has provided some poor experience. Do you mind sharing what issues you are seeing for which links and which points of access? We'd like to take a look and help change this experience for you.

Appreciate your help and feedback!

Hi ,

First I want to apologize for the experience that you've had with the documentation, it's definitely not what we want people to go through as they're trying to find the answers they need.

From your message it sounds like there are three main issues that you've called out, one around the redirects, another around working with service accounts and the last about the .Net examples in the Github project. I've been chatting with some folks internally and here's our next steps to fix this:

1. Redirects: With the recent push of quite a bit of new samples, guides, and sections, there was a lot of content that was moved around. There was a reindexing request added in with Google to fetch the new page structure and we temporarily put main page redirects in place to help prevent a number of 404s. It looks like the reindexing has been completed, so most of those links should now be fixed. I'll keep looking over the search links from different sites to ensure that the content reflects the current state of the site.
2. Github samples: We're looking at all of the samples in the Windows SDK repo to check their current viability and make updates to any that are out of date. Those changes should be coming in soon.
3. Service account documentation: I'm working on a guide now under the quickstarts to cover the concept of a service account, different tricks that can be employed for creating one, how collaborations have to be set up for them, and what they have access to. I know this one can tend to be frustrating because you expect it to have instant access to all files. I'm guessing you came across some errors here about the service account not having access to certain files in user accounts, or like restrictions.

As a potential next step, we do have a number of new quickstart guides for most tasks (with C# examples) over at https://developer.box.com/docs/quickstart-guides. There are some more extensive application examples over at https://developer.box.com/docs/use-case-recipes. 

Again, I want to apologize for the experience you've had here, and just know that we're working on getting these fixed up. If there are any other issues that you're running into please let me know. I'll add them to our update list so that we can explore some better approaches for breaking down the concepts in the docs.

- Jon

Thank you so much! I think that will address the issues I was having. I still can't access some links I found in some older forums, but as long as you're aware othe issue, I'm ok with that. For example https://developer.box.com/docs/service-account

I was finally able to make my particular implementation work, but it would have been a more pleasant experience if the quick start guide was detailed and lead to a working example.

Thanks,

Yassir

Good feedback on the quickstarts. I think there are a few concepts that are important for app development with Box that I'll work on highlighting and taking a streamlined "build your first app" target:

- Authentication / authorization (OAuth 2 / JWT)

- Token management (refresh tokens, downscoping tokens)

- Service accounts (what they are, how they can essentially be any user account, etc)

- Collaborations and folder / file permissioning (along with the service accounts, how to grant content access

- Error handling for program flow

I'll get the service account info up shortly, as that is the most important missing piece here.

I'll also start migrating a large number of sample applications over to the Box repo that we used to build the quickstart samples: https://github.com/jcleblanc/box-examples/.

Thanks again,

Jon

Just to follow up, I migrated some of the previous service account documentation from the previous site to the current one: https://developer.box.com/docs/service-account (the missing link you posted above). It provides a bit more information on service accounts, but now that we have the base level information I'm going to iterate on those docs to give more detail and code samples on how to set up all of the collaborations and permissions that I was talking about earlier. 

There are only skeleton samples. And some of the samples are just wrong - the code is obviously mistaken. Like this: https://developer.box.com/en/guides/users/provision/architecture/

The node example references methods that don't exist and has one json file versus two different skeleton files that aren't mentioned in the example code. One of the functions takes an optional argument that it immediately overwrites. Etc.

That use-case recipies etc only has admin level stuff about creating an app on the box web ui.