Postgraphile: Initial documentation site

[rojobuffalo]

As mentioned in #87, one the top priorities is a documentation website.

@calebmer Other than reference docs for the API, is there anything else that would be must-have for the first version of the docs site: e.x. contribution guidelines, getting started, tutorial, examples, blog, discussion forum, search, etc.? And would any items maybe not be must-have for version 1, but should be planned as short-term goals?

What are your thoughts on static site frameworks? Would you want to put this in a gh-pages branch on this repo or start a new repo like calebmer/postgraphql-docs or create an organization and do postgraphql/postgraphql.github.io?

[ferdinandsalis]

Thanks for bringing this up. In terms of how to do docs I also want to point to a new feature on github. You can now set the source of GithubPages to the master branch /docs folder. https://github.com/blog/2233-publish-your-project-documentation-with-github-pages

[calebmer]

Thanks so much! :blush:

Yep, I like @ferdinandsalis’s approach for now. In the future I do want to put PostGraphQL in its own organization, but for now it's fine in here.

One thing I’d like to see in the site is an advanced PostgreSQL tutorial teaching some core and useful strategies for schema design that work well with PostGraphQL (I could see a resources like this being super useful even for non users of PostgreSQL).

It would be really cool if we could run the forum example API on Heroku (with mutations disabled) and embed GraphiQL iframes (or links to a GraphiQL interface) on every page with example queries.

Once @ferdinandsalis is comfortable with the position of #66, I’d like to turn the experiences building that into a tutorial article. We’ll have to decide how deep we want that to go.

A major goal of mine with this site is to drive adoption. The thought being if we have a really attractive landing page and thorough guides with GraphiQL examples (which don’t require a line of code to be written by the user!) we can attract more users to PostGraphQL and thus the ecosystem we’re building.

So from an outline perspective I think important things to have (in the first pass) is:

• An attractive landing page.
• An easily accessible GraphiQL interface (this will probably need to be hosted on Heroku).
• A super basic getting started article.
• 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.
  
  
  • Stop overengineering with PostGraphQL (premise is that PostGraphQL has already been over-engineered, perhaps add to “evaluating PostGraphQL” section)
  
  
• 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 (once they’re supported…)
  
  
• Authentication/Authorization (also once they’re supported…)
• PostGraphQL as a CLI tool.
• PostGraphQL as HTTP middleware (basic http, express, connect, and koa examples would be awesome).

After that I’d like to see a tutorial based on @ferdinandsalis’s work with the Relay example (plus the experience of anyone else) as well as some quality articles on designing a good PostgreSQL schema.

Excited about PostGraphQL’s future 😊 :+1:

[rojobuffalo]

Using the docs directory is a cool feature I didn't know about. However, there may be constraints to that approach. Generally speaking, we would have a src directory and a build process that outputs everything to a build or dist or lib directory. But we have to move an index.html file outside so it sits at the top-level under docs.

If it were it's own repo, all the source could be on a master branch that builds to the docs directory; or the build directory could be subtree pushed to the gh-pages branch.

Maybe there's a static site framework that is designed for this; but that's just an issue that I had to solve with my personal github pages site recently.

Would it not bother anyone to post-hoc move a built index.html file outside of the build directory? Would that slow down development workflows?

[calebmer]

Yeah, I agree. I guess we do need our own repo then as the gh-pages branch as a means of deployment was discontinued.

I created a new repo and invited you both to collaborate :+1:

We’ll move this into a PostGraphQL organization at some point. The reason I’m hesitating to make a PostGraphQL organization is that while we’ll be focusing on PostgreSQL for a while, I want to think of a better, database agnostic name :wink:

[rojobuffalo]

Ok cool 👍. I'll dig into static site frameworks vs. roll-your-own unless you're leaning towards one in particular.

[ferdinandsalis]

@rojobuffalo for your consideration — https://github.com/gatsbyjs/gatsby

[rojobuffalo]

Thanks @ferdinandsalis
Just pushed a simple starting point: https://calebmer.github.io/postgraphql-docs/