Use more formal style in vignettes

[eoduniyi]

I had a question about how formal the documentation is supposed to be.

For example, the following:

 Thus, once _your_ data is in R's workspace, creating a `hyperSpec`{.r} object is easy.
We suggest wrapping the code to import your data and the line joining it into a `hyperSpec`{.r} object by _your_ own import function.
_You_ are more than welcome to contribute such import code to package **hyperSpec**.
Secion \@ref(sec:writing-Import)<!--, (p. \pageref{sec:writing-Import})--> discusses examples of custom import functions.

Could be written from a third-person perspective (more formal):

Thus, once the data is in R's workspace, creating a `hyperSpec`{.r} object is easy.
We suggest wrapping the code to import the data and the line joining it into a `hyperSpec`{.r} object by a user-created import function.
Users are more than welcome to contribute such import code to package **hyperSpec**.
Secion \@ref(sec:writing-Import)<!--, (p. \pageref{sec:writing-Import})--> discusses examples of custom import functions.

[GegznaV]

In my opinion, the style should be consistent throughout all the vignettes.

I think @eoduniyi's remark is good and I agree using a more formal style in situations like this.

---

@eoduniyi, some places of the vignettes can be totally overwritten to reflect the current situation of hyperSpec. I recommend reading the whole text of the vignette first without editing. And when you get the whole picture, it would be easier to fix/update the vignettes.

One more thing: fileio.Rmd should be split into separate vignettes which will be moved to appropriate packages. Otherwise, we will have to use "circular dependencies": hyperSpec should not depend on hySpc packages.

[bryanhanson]

Your instincts are correct Erick: re-write things in the style you suggest. As with #265 just go ahead and make these changes, you do not need to seek review on these stylistic changes. Just make them and merge them.

I will open another issue about how to split this vignette (per VG's comment above).

[eoduniyi]

@GegznaV so there should be a fileio.Rmd for all the different file formats?

[bryanhanson]

If it were up to me I'd keep all the file i/o stuff together. But, there is the complication that to keep hyperSpec independent of and not depending upon the file i/o packages we need to spin out the pieces since code runs in the vignettes (doesn't it?). @cbeleites your thoughts?

[eoduniyi]

If it were up to me I'd keep all the file i/o stuff together. But, there is the complication that to keep hyperSpec independent of and not depending upon the file i/o packages we need to spin out the pieces since code runs in the vignettes (doesn't it?). @cbeleites your thoughts?

@bryanhanson so like:

fileio_packges <- {hySpc.read.txt, ... , hySpc.io.format}
decompose(fileio.Rmd on fileio_packges)

So we could link (via URL) hyperSpec(vignette) <-> fileio_packges(vingette)

[bryanhanson]

The link would be via the list-of-vignettes.md mechanism.

If decompose means break it into pieces yes. One by one as new packages emerge.

[cbeleites]

I'm all for breaking the vignette into pieces.

So, for a new io package,

• a new vignette is started in that package.
• The package gets listed in hyperSpec's fileio vignette with the type of files it is good for.
  E.g. hySpc.read.txt (with link) for all kinds of ASCII/text based file formats.
• chunks are moved from hyperSpec's fileio vignette into the package vignette

In the end, hyperSpec's fileio vignette will be a switchyard to tell people which package to use for their data. The vignette of that package will explain how to exactly do that.

[GegznaV]

Does the name of this issue (Formality of vignettes) reflect the essence of this discussion?

Do we still discuss the style of English in the vignettes of about the way the fileio.Rmd vignettes should be split into pieces? (I suggeast renaming the issue)