4326 doc examples&replace fixes #4622

mheppler · 2018-04-26T12:42:01Z

Related Issues

connects to Guides - Review the use of examples #4326 Guides - Review the use of examples

Pull Request Checklist

Unit tests completed
Integration tests: None
Deployment requirements, SQL updates, Solr updates, etc.: None
Documentation completed
Merged latest from "develop" branch and resolved conflicts

Unrelated to rest of branch - noticed a bug when building the docs. The Windows page needed to be added to the index of the dev guide. Also changed the page title to be more descriptive.

Added details about draft datasets and metadata to build appropriate expectations and resolve user confusion.

Went through about half of our documentation to review use of examples. Made various small tweaks. Second half forthcoming.

Finished my review of the way we use examples in docs. Lots of small corrections.

Updated the example on the Install Prep page and fixed syntax on two tables.

coveralls · 2018-04-26T12:47:28Z

Coverage remained the same at 13.367% when pulling 07db977 on 4326-doc-examples&replace-fixes into c593125 on develop.

mheppler · 2018-04-26T12:48:23Z

doc/sphinx-guides/source/user/dataset-management.rst


-After successfully replacing a file, a new dataset draft version will be created. A summary of your actions will be recorded in the dataset Version Details table in the "Versions" tab on that dataset's page, and in the file Version Details table on the file's page. Both tables allow you to access all previous versions of the file across all previous versions of your dataset, including the old version of the file before you replaced it.
+After successfully replacing a file, a new dataset draft version will be created. A summary of your actions will be recorded in the "Versions" tab on that dataset's page, and in "Versions" tab on the file's page. Both tabs allow you to access all previous versions of the file across all previous versions of your dataset, including the old version of the file before you replaced it.


Suggested revision...

A summary of your actions will be recorded in the "Versions" tab on both the dataset page and file page.

mheppler · 2018-04-26T12:54:08Z

doc/sphinx-guides/source/user/find-use-data.rst

@@ -10,7 +10,7 @@ Finding Data
 Without logging in to Dataverse, users can browse Dataverse, search for dataverses, datasets, and files, view dataset descriptions and files for
 published datasets, and subset, analyze, and visualize data for published (restricted & not restricted) data files. To view an unpublished dataverse, dataset, or file, a user will need to be given permission from that dataverse's administrator to access it.

-A user can search the dataverses, datasets, and files within a particular dataverse by using the search bar found on a dataverse page. For example, if you are on the Murray Research Archive Dataverse page, you can search that specific dataverse's contents by using the search bar and/or facets displayed on the page.
+A user can search within a specific dataverse for the dataverses, datasets, and files it contains by using the search bar and facets found on that dataverse's page.


"...found on that dataverse's page" looked odd to me. Suggested revision...

A user can use the search bar and facets to discover the dataverses, datasets, and files contained within a specific dataverse.

mheppler

Added my $0.02 revision suggestions in comments on the commits view. Take them or leave. Approved for QA with or without further revision.

mheppler · 2018-04-26T13:03:25Z

doc/sphinx-guides/source/api/native-api.rst

@@ -339,7 +339,7 @@ A more detailed "add" example using curl::

 Example python code to add a file. This may be run by changing these parameters in the sample code:

-* ``dataverse_server`` - e.g. https://dataverse.harvard.edu
+* ``dataverse_server`` - e.g. https://dataverse.example.edu


Would it be too much effort to use example.dataverse.org as an example, and then setup a redirect for that example domain to demo.dataverse.org? @pdurbin...??

@mheppler good idea. Fixed in 83b8683

A couple of small rephrasings from Code Review suggestions.

pdurbin · 2018-04-26T18:15:02Z

Please no ampersands in branch names. I can work around this easily but check this out:

$ git checkout 4326-doc-examples&replace-fixes
[1] 98185
-bash: replace-fixes: command not found
murphy:guides.dataverse.org pdurbin$ error: pathspec '4326-doc-examples' did not match any file(s) known to git.

[1]+  Exit 1                  git checkout 4326-doc-examples

Thanks.

pdurbin

"Foobar College" is weird but otherwise this looks fine.

pdurbin · 2018-04-26T19:01:39Z

doc/sphinx-guides/source/installation/config.rst

@@ -695,7 +695,7 @@ See :ref:`Branding Your Installation` above.

 By default the footer says "Copyright © [YYYY]" but you can add text after the year, as in the example below.

-``curl -X PUT -d ", The President &#38; Fellows of Harvard College" http://localhost:8080/api/admin/settings/:FooterCopyright``
+``curl -X PUT -d ", Foobar College" http://localhost:8080/api/admin/settings/:FooterCopyright``


Foobar College?

pdurbin · 2018-04-26T19:39:13Z

doc/sphinx-guides/source/user/find-use-data.rst

@@ -10,7 +10,7 @@ Finding Data
 Without logging in to Dataverse, users can browse Dataverse, search for dataverses, datasets, and files, view dataset descriptions and files for
 published datasets, and subset, analyze, and visualize data for published (restricted & not restricted) data files. To view an unpublished dataverse, dataset, or file, a user will need to be given permission from that dataverse's administrator to access it.

-A user can search the dataverses, datasets, and files within a particular dataverse by using the search bar found on a dataverse page. For example, if you are on the Murray Research Archive Dataverse page, you can search that specific dataverse's contents by using the search bar and/or facets displayed on the page.
+A user can search within a specific dataverse for the dataverses, datasets, and files it contains by using the search bar and facets displayed on that dataverse's page.


I'm glad this MRA example was taken out. Nothing against the archive, it's just most people haven't heard of it.

dlmurphy added 5 commits April 17, 2018 13:19

Windows page - added to index

342154d

Unrelated to rest of branch - noticed a bug when building the docs. The Windows page needed to be added to the index of the dev guide. Also changed the page title to be more descriptive.

File Replace guide - details added [#4380]

8cb65f7

Added details about draft datasets and metadata to build appropriate expectations and resolve user confusion.

Review of examples in docs, part 1 [#4326]

cda4d41

Went through about half of our documentation to review use of examples. Made various small tweaks. Second half forthcoming.

Review of examples in docs, part 2 [#4326]

27b221d

Finished my review of the way we use examples in docs. Lots of small corrections.

Prep example update and table syntax #4326

55f65b0

Updated the example on the Install Prep page and fixed syntax on two tables.

mheppler commented Apr 26, 2018

View reviewed changes

Edits from Code Review [#4326]

845a7e4

A couple of small rephrasings from Code Review suggestions.

pdurbin added 3 commits April 26, 2018 14:20

use demo.dataverse.org in non-admin examples for native API #4326

ec184ce

ok to use demo server to test adding files #4326

83b8683

sorry case for postgres an solr #4326

8235d27

pdurbin approved these changes Apr 26, 2018

View reviewed changes

mheppler and others added 4 commits April 27, 2018 09:48

Merge branch 'develop' into 4326-doc-examples&replace-fixes

d58b975

Fixed a few typo's and misc writing style revisions [ref #4326]

1346843

mention pgAdmin3 and SchemaSpy

9acfcb3

please avoid ampersands in branch names

07db977

kcondon merged commit 07db977 into develop Apr 30, 2018

pdurbin added this to the 4.9 - Persistent Identifiers for Files milestone Apr 30, 2018

poikilotherm deleted the 4326-doc-examples&replace-fixes branch July 1, 2020 16:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

4326 doc examples&replace fixes #4622

4326 doc examples&replace fixes #4622

mheppler commented Apr 26, 2018

coveralls commented Apr 26, 2018 •

edited

Loading

mheppler Apr 26, 2018

mheppler Apr 26, 2018

mheppler left a comment

mheppler Apr 26, 2018

pdurbin Apr 26, 2018

pdurbin commented Apr 26, 2018

pdurbin left a comment

pdurbin Apr 26, 2018

pdurbin Apr 26, 2018


		After successfully replacing a file, a new dataset draft version will be created. A summary of your actions will be recorded in the dataset Version Details table in the "Versions" tab on that dataset's page, and in the file Version Details table on the file's page. Both tables allow you to access all previous versions of the file across all previous versions of your dataset, including the old version of the file before you replaced it.
		After successfully replacing a file, a new dataset draft version will be created. A summary of your actions will be recorded in the "Versions" tab on that dataset's page, and in "Versions" tab on the file's page. Both tabs allow you to access all previous versions of the file across all previous versions of your dataset, including the old version of the file before you replaced it.

4326 doc examples&replace fixes #4622

4326 doc examples&replace fixes #4622

Conversation

mheppler commented Apr 26, 2018

Related Issues

Pull Request Checklist

coveralls commented Apr 26, 2018 • edited Loading

mheppler Apr 26, 2018

Choose a reason for hiding this comment

mheppler Apr 26, 2018

Choose a reason for hiding this comment

mheppler left a comment

Choose a reason for hiding this comment

mheppler Apr 26, 2018

Choose a reason for hiding this comment

pdurbin Apr 26, 2018

Choose a reason for hiding this comment

pdurbin commented Apr 26, 2018

pdurbin left a comment

Choose a reason for hiding this comment

pdurbin Apr 26, 2018

Choose a reason for hiding this comment

pdurbin Apr 26, 2018

Choose a reason for hiding this comment

coveralls commented Apr 26, 2018 •

edited

Loading