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.