"Installing the SDK" section in the java version looks like it's part of the numbered sections

[dogeared]

Perhaps this should be italicized or a smaller heading?

[lhazlewood]

I don't think it should be smaller. To me, this is step 1 in the quickstart and should be labeled accordingly (i.e. currently that would be 3.1)

[lhazlewood]

Just curious - why was this closed @jakubswiatczak ?

[jakubvul]

Hey Les, I added it as a section 2.3 of Setup here: https://github.com/stormpath/stormpath-documentation/commit/b222b9a286d4cdff19ccb02cf853d5f025c16585

I mentioned it in the commit.

Making it section x.1 doesn't really work with our multi-language output, so it's the last step of Set-Up, which was how we had it in the original outline that Tom and I worked on back in Sept/Oct.

[lhazlewood]

What? This is the very first thing that any SDK needs to do - to get the library (either via NuGet, NPM, Maven Central, etc). This should be the very first thing in the list, not the last - I'm very confused. Can we change this? cc @omgitstom

[jakubvul]

All of the steps in Setup are required in order to proceed with the Quickstart, so having SDK Installation as the final step of Setup (2.3), before you go on to the Quickstart (3.x) I think is equivalent to having it as the first section of the Quickstart.

Additionally, all of our SDK-only sections by design come at the end of various chapters. This has a couple of goals:

1. It preserves section numbering between the various guides. For example, Section 3.1 of Setup will be the same regardless of whether you're looking at the REST Guide or the Java Guide.
2. It stops us from having section headings that look like this, which I would argue is unnecessarily complicated and difficult to read:

.. only:: csharp or vbnet or java or nodejs or php or python

  3.2 Retrieve Your Application
  =============================

.. only:: rest

  3.1. Retrieve Your Application
  ===============================

[lhazlewood]

A quickstart should essentially have the format of "I've landed on a page. In this page - without redirecting me to other pages - take me from zero to a having a basic sample up and running".

Is that accomplished with the current format? Or do they have to visit more than one page?

[lhazlewood]

My goal here is one of optimized user experience. I hope that it doesn't sacrifice ideal doc unity across languages, but if we can't obtain that, UX should win.

[jakubvul]

@lhazlewood I definitely see the UX value in that, and I'd also prefer to keep the clicking between pages to a minimum. How about this:

1. About Stormpath

2. Quickstart

   2.1 Sign-up for Stormpath

   2.2. Create an API Key Pair

   2.3. Install the SDK

   2.4. Retrieve Your Application

   2.5. Create a User Account

   2.6. Authenticate a User Account

   2.7. Next Steps

[lhazlewood]

Big :+1: for the SDK documentation for using this TOC.

However, framework quickstarts are much shorter because retrieve app/create user/authenticate user stuff is already built. For example: https://docs.stormpath.com/java/spring-boot-web/quickstart.html

I assume this issue relates only to the SDK documentation.

[jakubvul]

Correct. Integrations will not have their documentation generated from this repo because their structure and functionality are so different.

[jakubvul]

So the approach of having different headings depending on what language you're in isn't possible, because Sphinx doesn't render language-specific headings properly. We've made a Github issue on the Sphinx project: https://github.com/sphinx-doc/sphinx/issues/2385

Here's what we're going to do instead: Setup and Quickstart are now one, and Step 2.3 looks like this:

2.3 Installing the SDK
======================

.. only:: rest

  This step is not relevant to the REST Product Guide, but would be required if you were using one of our SDKs:

  - `C# <https://docs.stormpath.com/csharp/product-guide/latest/>`__
  - `Java <https://docs.stormpath.com/java/product-guide/latest/>`__
  - `Node.js <https://docs.stormpath.com/nodejs/product-guide/latest/>`__
  - `Python <https://docs.stormpath.com/python/product-guide/latest/>`__
  - `VB.net <https://docs.stormpath.com/vbnet/product-guide/latest/>`__

.. only:: csharp or vbnet

  To set up your environment follow these steps:

[...]