Restructure documentation

[iuliadmtru]

This is a continuation of #177. The new proposed documentation structure is:

docs/
└───src/
│   │   api.md                -> contains index and API
│   │   getting_started.md    -> contains installation guide and short tutorial
│   │   index.md              -> first page of the documentation, contains introduction
│   │   manual.md             -> contains package details (implementation, math, performance details)
│   │
│   └───assets/
│       │   plots

(Proposed) Tasks:

• Introduction
• Tutorial
• Manual
  • DataFrames dependence in Survey
  • Bootstrapping (why we chose it and what else we're considering)
  • Plotting - AlgebraOfGraphics (and, consequently, Makie) dependence in Survey
  • Comparison with other survey analysis tools
  • Future plans

[iuliadmtru]

I suggest removing the "Moving from R to Julia" section. The API reference and tutorial is enough to accommodate the new user.

[iuliadmtru]

Actually, we could name the last subsection in the manual "Comparison with R" and add there what's in the "Moving from R to Julia" section now. (This is what DataFrames does.) We could add performance comparisons there as well (as a subsubsection), or have a dedicated section for performance where we just have benchmarks, no comparisons. What do you think @ayushpatnaikgit?

[ayushpatnaikgit]

Actually, we could name the last subsection in the manual "Comparison with R" and add there what's in the "Moving from R to Julia" section now. (This is what DataFrames does.) We could add performance comparisons there as well (as a subsubsection), or have a dedicated section for performance where we just have benchmarks, no comparisons. What do you think @ayushpatnaikgit?

1. I think in the future, we'll have moving from SAS, STATA as well, so we should plan accordingly.
2. We shouldn't have benchmarks in the documentation. We should have them in the readme or in a blog article.

[iuliadmtru]

1. I think in the future, we'll have moving from SAS, STATA as well, so we should plan accordingly.

Then how about a more generic subsection name such as "Comparisons" and have subsubsections for "Comparison with R", "Comparison with SAS" etc?

2. We shouldn't have benchmarks in the documentation. We should have them in the readme or in a blog article.

Ok, got it. Then maybe keep the "Performance" subsection where we mention how we took performance into consideration and what we plan to do next?

[ayushpatnaikgit]

1. I think in the future, we'll have moving from SAS, STATA as well, so we should plan accordingly.

Then how about a more generic subsection name such as "Comparisons" and have subsubsections for "Comparison with R", "Comparison with SAS" etc?

2. We shouldn't have benchmarks in the documentation. We should have them in the readme or in a blog article.

Ok, got it. Then maybe keep the "Performance" subsection where we mention how we took performance into consideration and what we plan to do next?

1. Comparisons isn't informative to someone unfamiliar with the context. Comparison with other languages will be better.
2. Let's keep all performance related things to blog articles and not the documentation. They aren't many Julia packages that show performance in the documentation. However, I think 1–2 examples in the readme could be okay, but let's have that discussion in an issue.

[smishr]

DataFrames.jl - Comparison with Python/R/Stata could be kept in mind.

I think one section with our vision and future plans with the package would be useful in the documentation. We can combine text from our ppts and previous work

[iuliadmtru]

Alright, I think I'm done with my part.

In the Comparison section I only added comparison with R. Other languages can be added later.

For Bootstrapping and Future plans I think it's better if you work on it @ayushpatnaikgit, @smishr. I suggest we merge this PR and add separate PRs for those. Before merging, we should replace the TODO in getting_started.md, line 80 with some actual information.

And regarding Bootstrapping, this section is only temporary. In the future there will be other methods for creating replicate designs. Maybe the section should be named Replicate designs?

[codecov-commenter]

Codecov Report

Merging #193 (b9515ab) into singledesign (26b89f4) will not change coverage.
The diff coverage is 100.00%.

@@              Coverage Diff              @@
##           singledesign     #193   +/-   ##
=============================================
  Coverage         96.17%   96.17%           
=============================================
  Files                12       12           
  Lines               157      157           
=============================================
  Hits                151      151           
  Misses                6        6           

Impacted Files	Coverage Δ
src/bootstrap.jl	100.00% <ø> (ø)
src/boxplot.jl	100.00% <ø> (ø)
src/hist.jl	91.66% <ø> (ø)
src/plot.jl	100.00% <ø> (ø)
src/ratio.jl	100.00% <ø> (ø)
src/SurveyDesign.jl	93.75% <100.00%> (ø)
src/quantile.jl	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[ayushpatnaikgit]

@smishr can you take a final look and then merge it?