Website TODO list

[calebmer]

BENJIE'S NOTE: this post was originally written by @calebmer on the PostGraphQL repo (since renamed to PostGraphile); since then we have built a website (https://graphile.org) but many of these points are still salient so we'll keep this issue open until they're dealt with.

PostGraphQL needs a documentation/marketing website. As a frontend engineer I’d love to build it myself, but at the same time PostGraphQL needs improvements in areas like performance. Here is an outline for what I want in the site (of course these specifications are subject to change):

• An attractive landing page.
• An easily accessible GraphiQL interface (this will probably need to be hosted on Heroku).
• A super basic getting started article.
• Forum example tutorial.
• Helpful articles:
  • Example Queries.
  • Documenting your schema (with Postgres COMMENT).
  • Deploying PostGraphQL with Docker.
  • Deploying PostGraphQL with PM2.
  • Extending your database with triggers and LISTEN/NOTIFY.
  • Writing JavaScript or Ruby in your Postgres logic.
  • Understanding graph database terms in GraphQL.
  • Backing up your Postgres database.
  • Why you should use PostGraphQL (persuasive, stop overengineering, etc.)
• Documentation.

…and here’s a quick outline for documentation:

• Tables.
  • Queries.
    • Relationships.
    • Unique keys.
  • Mutations.
• Procuedures.
  • Mutations.
  • Queries.
  • Connections.
  • Computed fields.
• Custom types.
  • Domain types.
  • Enum types.
  • Composite types.
• Authentication/Authorization.
• PostGraphQL as a CLI tool.
• PostGraphQL as HTTP middleware, basic examples of the web techs would be awesome:
  • http
  • express
  • connect
  • koa

[angelosarto]

@calebmer I'm not much in the way of a designer, but I can provide some technical content/articles. Has anyone volunteered to setup the basic page?

[benjie]

@angelosarto That would be very welcome. Since we don't have anything like that set up yet I think we should just follow the https://pages.github.com/ example set up. In fact I might look into that now...

[benjie]

Okay; I just created the relevant repository which has created the basic site. I chose the Merlot theme because it seems to fit with our logo quite well.

I'll add you as a contributor - feel free to do what you feel is necessary - we won't publicise it until it's ready.

[ab-pm]

Should this issue be moved to the documentation repository and updated (to keep an ideas list for further pages) or just closed?

[benjie]

For anyone interested (@ab-pm?) rather than me checking off boxes that I feel are done, I'd appreciate someone else signing them off and saying that they're sufficiently done. Many of these things are at least started, but that doesn't mean they're good enough to check off. Here's a list you can copy/paste into your own comment and check off as appropriate, I've trimmed a few out that are more complex to address (like the hosted GraphiQL).

- [ ] A super basic getting started article.
- [x] Forum example tutorial.
- [ ] Helpful articles:
  - [x] Example Queries.
  - [ ] Documenting your schema (with Postgres `COMMENT`).
  - [ ] Deploying PostGraphQL with Docker.
  - [ ] Deploying PostGraphQL with PM2.
  - [ ] Extending your database with triggers and `LISTEN`/`NOTIFY`.
  - [ ] Writing JavaScript or Ruby in your Postgres logic.
  - [ ] Understanding graph database terms in GraphQL.
  - [ ] Backing up your Postgres database.
  - [ ] Why you should use PostGraphQL (persuasive, stop overengineering, etc.)
- [ ] Documentation.

…and here’s a quick outline for documentation:
- [ ] Tables.
  - [ ] Queries.
    - [ ] Relationships.
    - [ ] Unique keys.
  - [ ] Mutations.
- [ ] Procuedures.
  - [ ] Mutations.
  - [ ] Queries.
  - [ ] Connections.
  - [ ] Computed fields.
- [ ] Custom types.
  - [ ] Domain types.
  - [ ] Enum types.
  - [ ] Composite types.
- [ ] Authentication/Authorization.
- [x] PostGraphQL as a CLI tool.
- [ ] PostGraphQL as HTTP middleware, basic examples of the web techs would be awesome:
  - [ ] `http`
  - [ ] `express`
  - [ ] `connect`
  - [ ] `koa`