Skip to content

Move usage guides to their own docs. #6238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
tswast merged 4 commits into from
Oct 19, 2018
Merged

Move usage guides to their own docs. #6238

tswast merged 4 commits into from
Oct 19, 2018

Conversation

@tswast
Copy link
Contributor

@tswast tswast commented Oct 17, 2018

The API reference links were buried behind pages of
code samples. Moving the how-to guides to their own
pages makes the documentation easier to navigate.
@tswast tswast requested a review from alixhami October 17, 2018 17:27
@tswast tswast requested a review from crwilcox as a code owner October 17, 2018 17:27
@googlebot googlebot added the cla: yes This human has signed the Contributor License Agreement. label Oct 17, 2018
@tswast tswast added api: bigquery Issues related to the BigQuery API. type: docs Improvement to the documentation for an API. labels Oct 17, 2018
alixhami
alixhami requested changes Oct 17, 2018
View reviewed changes
bigquery/docs/index.rst Outdated
@@ -1,408 +1,22 @@
.. include:: /../bigquery/README.rst

Using the Library

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

bigquery/docs/howto/tables.rst Outdated
:start-after: [START bigquery_load_from_file]
:end-before: [END bigquery_load_from_file]

Load table data from Google Cloud Storage

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

alixhami
alixhami reviewed Oct 18, 2018
View reviewed changes
bigquery/docs/index.rst Outdated

.. code-block:: bash
More Examples
-------------

This comment was marked as spam.

Sign in to view

bigquery/docs/howto/datasets.rst Outdated
`Datasets <https://cloud.google.com/bigquery/docs/datasets>`_.


Dataset operations

This comment was marked as spam.

Sign in to view

This comment was marked as spam.

Sign in to view

@tseaver
Copy link
Contributor

tseaver commented Oct 19, 2018

I have a question, rather than a direct review comment: would it be better to call the section usage than howto? Right now we have a page, /usage.html, which redirects to /index.html: that suggests that usage is part of the expected documentation pattern.
@tswast
Copy link
Contributor Author

tswast commented Oct 19, 2018

Would it be better to call the section usage than howto?

I chose howto because that's in line with our GCP tech writing style guide, but you're right that usage.html is the existing pattern in this library. Maybe I should move the subsections that I put in index.rst to their own usage/index.rst file?
tswast added 4 commits October 19, 2018 09:25
@tswast
Move usage guides to their own docs.
6880456 
The API reference links were buried behind pages of code samples. Moving the how-to guides to their own pages makes the documentation easier to navigate.
@tswast
Reorganize howto guides into sections. Add links to relevant methods.
5b807db
@tswast
Move 'more examples' to bottom of the examples section.
c286e23 
Add section headers to Dataset how-to guides.
@tswast
Move howto to usage directory
75972b1
@tswast tswast merged commit 9108464 into googleapis:master Oct 19, 2018
@tswast tswast deleted the bq-usage-docs branch October 19, 2018 17:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api: bigquery Issues related to the BigQuery API. cla: yes This human has signed the Contributor License Agreement. type: docs Improvement to the documentation for an API.

4 participants

@tswast @tseaver @alixhami @googlebot