Guides - Review the use of examples

[dlmurphy]

Inspired by a discussion on our Slack, let's do a comprehensive review of the way we use concrete examples in our documentation. We sometimes use Harvard Dataverse as an example to illustrate how Dataverse can be configured, or how certain features work. It can be helpful to have a concrete example to point to in order to explain exactly how a feature works.

However, we've seen a recent exchange on social media where one of the examples in our guides caused user confusion. We mentioned that Harvard Dataverse imposes a 2GB limit on tabular data file upload in order for ingest to work. The user took this to mean that the Dataverse software imposes a 2GB limit.

Let's review each example in our guides and determine whether these examples are actually illustrative or should be rephrased or removed. This can help us decide whether we should continue using Harvard Dataverse as an example in our guides.

[pdurbin]

Some example URLs I know we use in the guides as of 4.8.3:

• https://dataverse.example.edu
• https://example.dataverse.edu
• https://dcm.example.edu

[pdurbin]

@dlmurphy I'm going to tweak an example hostname in pull request #4585. Any guidance on which hostname to use? Thanks!

[dlmurphy]

@pdurbin I like to have examples look totally obviously fabricated just to remove any ambiguity around them. So for this pull request, I'd suggest something like:

"hostname": "dataverse.example.edu",
"name": "Exampleverse",

[dlmurphy]

I've gone through all of our documentation and reviewed the way we use examples. I've made some tweaks here and there to improve them. Overall, we're in a good place. Here are my main takeaways:

• Examples are a useful way to clarify especially complex or abstract aspects of our software. They're especially handy when talking about fiddly settings as on the config page of the Installation Guide. On the whole, we use examples appropriately throughout all guides.

• When referring to a hypothetical Dataverse installation in an example, it's good to use an obviously made-up name so the reader always knows they're looking at a hypothetical example. We tend to use dataverse.example.edu, dataverse.example.com, or dataverse.foobar.edu. Each of these are good.

• It's best not to use Harvard Dataverse as an example, unless there's a particularly compelling reason to do so. When we talk about features or settings specific to Harvard Dataverse, we risk confusing readers by implying that the way we do it at Harvard is how it is across all installations.

I've made several small edits to address these takeaways.

[dlmurphy]

While going over our guides, I found one example that might be out of date, on our Installation Prep page. Phil let me know that @kcondon or @landreev can probably help make sure this information is current:

In contrast, the production installation at https://dataverse.harvard.edu is currently backed by six servers with two Intel Xeon 2.53 Ghz CPUs and either 48 or 64 GB of RAM. The three servers with 48 GB of RAM run are web frontends running Glassfish and Apache and are load balanced by a hardware device. The remaining three servers with 64 GB of RAM are the primary and backup database servers and a server dedicated to running Rserve. Multiple TB of storage are mounted from a SAN via NFS. The :ref:advanced section shows a diagram (a seventh server to host Geoconnect will probably be added).

[TaniaSchlatter]

All sound like good changes! - Tania

…

On Apr 23, 2018, at 4:42 PM, Derek Murphy ***@***.***> wrote: I've gone through all of our documentation and reviewed the way we use examples. I've made some tweaks here and there to improve them. Overall, we're in a good place. Here are my main takeaways: Examples are a useful way to clarify especially complex or abstract aspects of our software. They're especially handy when talking about fiddly settings as on the config page of the Installation Guide. On the whole, we use examples appropriately throughout all guides. When referring to a hypothetical Dataverse installation in an example, it's good to use an obviously made-up name so the reader always knows they're looking at a hypothetical example. We tend to use dataverse.example.edu, dataverse.example.com, or dataverse.foobar.edu. Each of these are good. It's best not to use Harvard Dataverse as an example, unless there's a particularly compelling reason to do so. When we talk about features or settings specific to Harvard Dataverse, we risk confusing readers by implying that the way we do it at Harvard is how it is across all installations. I've made several small edits to address these takeaways. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[landreev]

We should probably keep the paragraph above, as an example of a production setup running on "real" hardware ("real", as opposed to virtual Amazon instances).

Maybe something along the lines of "As for the production installation at https://dataverse.harvard.edu, before it was moved out to the Amazon cloud it was backed by six physical servers, ..." etc. (but drop the sentence on Geoconnect, currently in parentheses - "a seventh server to host Geoconnect...").

And then:

"Currently, Harvard Dataverse is served by four AWS server nodes: two "m4.4xlarge" instances (64GB/16 vCPU) as web frontends, one 32GB/8 vCPU ("m4.2xlarge") instance for the SOLR search engine and and one 16GB/4 vCPU ("m4.xlarge") instance for R and TwoRavens. PostgresQL database is served by Amazon RDS and physical files are stored on Amazon S3."

I don't think we need to mention Geoconnect at all. (it's not something we encourage anyone else to install - it's a service that we run and provide for other Dataverse installations; and it's always been clearly separated from our main production cluster).
If you feel we need to mention it, here or somewhere else in the guides, it should be something like "Geoconnect, used by Harvard Dataverse and provided as a service for all the remote Dataverse installations, runs on a standalone Heroku instance".

[landreev]

@dlmurphy - I'm giving it back to you, for the final prettificaton...

[dlmurphy]

Looking good, passing this on to code review!

Note that this branch includes many tiny fixes to various parts of the guides, including a few things unrelated to this ticket.

[pdurbin]

As discussed with @mheppler and @dlmurphy this morning, I made a couple tweaks to mention https://demo.dataverse.org as the server to test with in the API guide. I also fixed some cApiTALizAtiON weirdness in the Installation Guide. I think "Foobar College" is weird but whatever. Off to QA!