Design Documents

[sourish-cmi]

1. Current documentation removes all the examples I provided in the initial documents. But those initial examples had to remove because it was taking too much time to compile - how can we bring those examples back?

2. We need to accommodate the case studies that data scientists are making as part of the CRRao package. How can we bring those case studies as part of the documentation?

[codetalker7]

For 1, we can add the old examples (just the code, we won't run that code during the documentation build to save time) to the docstrings for the corresponding functions. This is what Shouvik is doing right now.

In the current documentation, there is a guide (https://xkdr.github.io/CRRao.jl/dev/man/guide/) in which there are two examples; one for Frequentist and one for Bayesian. For other examples, users should be able to just directly go to the API docs for whatever model they want to use, and see an example for that.

[ajaynshah]

a. We should study Zelig for documentation design.

b. In my opinion (not deeply thought, just writing here), there is a need for 3 kinds of documentation. 1. Unix man pages: perfect, terse, precision above all. 2. A gentle introduction that gets a person started: from 0 until the point till they are able to read the man pages. 3. A JSS article which shows objectives, design philosophy, comparisons with other systems (in this case Zelig), critical elements of thought on the design, demonstrate correctness, measure performance, discuss future roadmap.

[sourish-cmi]

• I would like all examples for Frequestist cases to be back.
• For Bayesian cases, keep only Ridge and Laplace prior cases with sim_size=501

[codetalker7]

PR #28 (review) adds back all the examples to the respective docstrings, both for the frequentist models and the bayesian models.

[sourish-cmi]

On a different note - I thought - we could put all the examples and more detail on the "Wiki" (https://github.com/xKDR/CRRao.jl/wiki)

Keep the documentation clean and tight.

What do you think?

@ajaynshah @ayushpatnaikgit @codetalker7 @ShouvikGhosh2048

[ayushpatnaikgit]

We have added all the examples under API. They'll also be available to the user through the REPL.