Skip to content
This repository has been archived by the owner on Feb 1, 2023. It is now read-only.

Integrator documentation #213

Open
7 tasks
amercader opened this issue May 9, 2017 · 4 comments
Open
7 tasks

Integrator documentation #213

amercader opened this issue May 9, 2017 · 4 comments
Labels
api enhancement github pilots s3

Comments

@amercader
Copy link
Member

amercader commented May 9, 2017 •
edited
Loading

Description

Coupled with big improvements in UX we need to prioritise a clear and comprehensive documentation that guides users on how to make the most of the service. There should be a general introduction to data validation and how the service works.

The critical parts are how to enable / add sources and the goodtables.yml syntax. For adding sources we need dedicated page for each backend covering specifics:

  • GitHub: triggers created, permissions, badges, status checks
  • Amazon S3: permissions, regions (?)

We also need a page for more advanced topics like the API and authorization. And when they are in place, different plans.

My suggestion is to set up a separate static site on a custom subdomain (help.goodtables.io) that allows us to iterate and improve the docs fast.

Tasks

  • Set up a static site that autodeploys via Travis or similar
  • Design that matches the main goodtables.io site
  • Service overview, CI analogy, good examples of sources and erorrs
  • Add GitHub repo
  • Add Amazon S3 bucket
  • goodtables.yml syntax
  • API and authorization

Estimate

4
@amercader amercader added this to the Gamma milestone May 9, 2017
@danfowler
Copy link

In my role as Developer Advocate, I would be interested in assisting here.

@amercader
Copy link
Member Author

@danfowler That would be great! Is there something else important you think we should cover?

@danfowler
Copy link

  • Minimum permissions for S3 user integration

@roll roll mentioned this issue Jun 13, 2017
Merged
@gabelula
Copy link

gabelula commented Jul 6, 2017

Add good examples on goodtables.yml and sources.

@amercader amercader added [4d] and removed [2d] labels Oct 3, 2017
@amercader amercader changed the title Documentation Integrator documentation Oct 3, 2017
@vitorbaptista vitorbaptista mentioned this issue Dec 1, 2017
Merged
vitorbaptista added a commit that referenced this issue Dec 6, 2017
@vitorbaptista
[#213] Add initial documentation using Sphinx
6895bc7 
It contains:

* Quickstart on GitHub
* Writing a table schema
* Configuring goodtables.io
* A (small) goodtables.yml reference

It's missing docs for AWS, and the layout is still the default Sphinx theme.
vitorbaptista added a commit that referenced this issue Dec 6, 2017
@vitorbaptista
[#213] Add initial documentation using Sphinx
aad6285 
It contains:

* Quickstart on GitHub
* Writing a table schema
* Configuring goodtables.io
* A (small) goodtables.yml reference

It's missing docs for AWS, and the layout is still the default Sphinx theme.
vitorbaptista added a commit that referenced this issue Dec 10, 2017
@vitorbaptista
[#213] Improve docs theme
0b33ff8
vitorbaptista added a commit that referenced this issue Dec 10, 2017
@vitorbaptista
[#213] Add intial API documentation
9de2618 
The docs were generated using the OpenAPI specification. Ideally, the
specification file would be generated directly from our API definition, so
they're always in sync. We don't do it now, but will in the future.
vitorbaptista added a commit that referenced this issue Dec 10, 2017
@vitorbaptista
[#213] Improve docs theme
ee077be
vitorbaptista added a commit that referenced this issue Dec 10, 2017
@vitorbaptista
[#213] Add intial API documentation
8b5b3d5 
The docs were generated using the OpenAPI specification. Ideally, the
specification file would be generated directly from our API definition, so
they're always in sync. We don't do it now, but will in the future.
vitorbaptista added a commit that referenced this issue Dec 12, 2017
@vitorbaptista
[#213] Add initial documentation using Sphinx
8606670 
It contains:

* Quickstart on GitHub
* Writing a table schema
* Configuring goodtables.io
* A (small) goodtables.yml reference

It's missing docs for AWS, and the layout is still the default Sphinx theme.
vitorbaptista added a commit that referenced this issue Dec 12, 2017
@vitorbaptista
[#213] Improve docs theme
3f5adff
vitorbaptista added a commit that referenced this issue Dec 12, 2017
@vitorbaptista
[#213] Add intial API documentation
ee80b69 
The docs were generated using the OpenAPI specification. Ideally, the
specification file would be generated directly from our API definition, so
they're always in sync. We don't do it now, but will in the future.
vitorbaptista added a commit that referenced this issue Dec 13, 2017
@vitorbaptista
[#213] Fix custom CSS inclusion
12655e2
vitorbaptista added a commit that referenced this issue Dec 13, 2017
@vitorbaptista
[#213] Fix custom CSS inclusion
5f90cff
vitorbaptista added a commit that referenced this issue Dec 13, 2017
@vitorbaptista
[#213] Optimize PNG screenshot
61469ea 
The file size reduced about ~80%
vitorbaptista added a commit that referenced this issue Dec 15, 2017
@vitorbaptista
[#213] Add Amazon S3 documentation
741b8fe
vitorbaptista added a commit that referenced this issue Dec 15, 2017
@vitorbaptista
[#213] Reorganize files into folders
8dfa2dc 
This makes the URIs nicer.
vitorbaptista added a commit that referenced this issue Jan 25, 2018
@vitorbaptista
[#213] Add Amazon S3 documentation
fc1bee3
vitorbaptista added a commit that referenced this issue Jan 25, 2018
@vitorbaptista
[#213] Reorganize files into folders
e5f259f 
This makes the URIs nicer.
vitorbaptista added a commit that referenced this issue Jan 25, 2018
@vitorbaptista
[#213] Add Amazon S3 documentation
87cc462
vitorbaptista added a commit that referenced this issue Jan 25, 2018
@vitorbaptista
[#213] Reorganize files into folders
e4cf7b4 
This makes the URIs nicer.
@roll roll added enhancement and removed [4d] labels May 20, 2019
@roll roll removed this from the Gamma milestone Jun 3, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
api enhancement github pilots s3
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@gabelula @amercader @roll @danfowler