Documentation Improvements

Feature Requests
1

This is a thread to capture any feedback on areas you think the documentation site (https://docs.convox.com/) is lacking, things you spot that are out of date or confusing, or entirely new docs that deserve to be created.

So, what would you like to see on the docs site? :blush:

3

One area that I think it could be more clear that caught me was that the environment variable if you set it in the console or via cli, you must also add it to the conovox.yml file. Even thought the docs do say

Environment variables must be specified to be available to your running application.

In my opinion is not clear enough that they must existe in the convox.yml and had to spend bunch of time figuring out why they were not working correctly.

4

How resources are declared is not clear from the the docs. If you look at convox-yml docs it shows an example like this:

resources:
  maindb:
    type: mysql
services:
  web:
    resources:
      - maindb

where resources and services are at the same level of indentation and under the web services you declare the resouce.

But in the resources docs it shows an example like this:

resources:
  maindb:
    type: mysql
  services:
    web:
      resources:
        - maindb

where services is inside the resources and also declare the resource inside the web service.

What is the correct indentation?

5

Thanks for spotting that @moises, the first example is correct, I’ll fix up the other document!

6

I haven’t used Convox on a project in literally years – I think my use either predated Console or straddled its launch, I used it w/the Weave AMI a while back – and I’m coming back to it now that it’s using k8s + terraform (and is multi-cloud too, yikes that’s awesome!)

First thing that I ran into: I often found/find myself clicking the very visible ‘Version 2’ in the sticky footer.

Why? Well, there’s nothing in the docs that say ‘V3’, or ‘current’, or anything.

So I think “Maybe V2 is the next, latest-and-greatest!”

Also, my heuristic would normally be “which styles/css looking dated/older?”, but in this case that led me astray – they’re similar, and I like the denser current docs better, but I legitimately thought that the V2 docs ‘looked new’, just because of slightly more whitespace, content, and brighter links in the left-hand sidebar.

Of course, now I’ve learned the distinction, through repeated exposure/confusion – V3 / Gen 3 is the good stuff. 3. Not 2.

Just thinking that maybe a 3 should be up in the title of the docs then. Or the ‘Version 2’ should be ‘Version 2 (previous gen)’ or summat.

Edit: also, just noticed – the copyright in that footer is even newer on the V2 docs than the (unlabled-as) V3 docs, 2020 vs 2019.