Skip to content

Commit e620c0e

Browse files
vissarionvissarion
committed
Adding GeomScale tutorial GSoD applcation
1 parent d80bde6 commit e620c0e

File tree

1 file changed

+168
-0
lines changed

1 file changed

+168
-0
lines changed

‎_posts/2023-03-24-GeomScale-tutorials.md

+168
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
layout: single
3+
title: "Create GeomScale Tutorials"
4+
date: 2023-03-24
5+
author: GeomScale
6+
author_profile: true
7+
read_time: true
8+
comments: true
9+
share: true
10+
related: true
11+
hidden: false
12+
---
13+
14+
15+
# Create GeomScale Tutorials
16+
17+
> Open call for documentation development
18+
19+
## About the organization
20+
21+
GeomScale is a research and development project that delivers open source code for
22+
state-of-the-art algorithms at the intersection of *data science*, *optimization*, *geometric*,
23+
and *statistical computing*. The current focus of GeomScale is scalable algorithms for
24+
sampling from high-dimensional distributions, integration, convex optimization,
25+
and their applications. One of our ambitions is to fill the gap between theory and
26+
practice by turning state-of-the-art theoretical tools in geometry and optimization
27+
to state-of-the-art implementations. We believe that towards this goal, we will
28+
deliver various innovative solutions in a variety of application fields, like finance,
29+
computational biology, and statistics that will extend the limits of contemporary
30+
computational tools. GeomScale aims in serving as a building block for an international,
31+
interdisciplinary, and open community in high dimensional geometrical and statistical
32+
computing.
33+
34+
The main development is currently performed in volesti, a generic open
35+
source `C++` library, with `R` and `Python` interfaces, for high-dimensional sampling,
36+
volume approximation, and copula estimation for financial modelling.
37+
In particular, the current implementation scales up to hundred or thousand
38+
dimensions, depending on the problem. It is the most efficient software package
39+
for sampling and volume computation to date. It is faster by orders of magnitude
40+
compared to packages that solve the same problems in several cases.
41+
It can compute challenging multivariate integrals and approximate optimal
42+
solutions in optimization problems.
43+
44+
It has already found important applications
45+
in systems biology, for [analyzing large metabolic networks](https://arxiv.org/pdf/2012.05503.pdf)
46+
(e.g., the latest human network), and in FinTech for detecting shock events and
47+
evaluating portfolios performance in stock markets with thousands of assets.
48+
Other application areas include AI and in particular approximate weighted
49+
model integration and data-driven power systems in control.
50+
51+
## About the project
52+
53+
### The problem
54+
55+
GeomScale develops scientific and research oriented software, therefore,
56+
detailed and well written documentation is an important requirement to reach the
57+
communities, the users, the practitioners, and the researchers it may concern.
58+
59+
GeomScale’s software can solve several complex and high dimensional problems efficiently
60+
in various fields; so our aim now is to create the essential tools to make it well-known
61+
and easily accessible across open source communities.
62+
63+
The main bottleneck for onboarding new contributors to GeomScale is the nature
64+
of the project that requires knowledge from various fields of advanced applied
65+
mathematics and theoretical computer science. The creation of a complete and
66+
detailed documentation will be a valuable tool towards overcoming that burden.
67+
Therefore, solid documentation is a stepping stone to grow our organization to
68+
become the reference open source software in geometric and statistical computing
69+
in high dimensions.
70+
71+
We aim to adopt the documentation system of [divio](https://documentation.divio.com/).
72+
73+
According to this system there are four types of documentation:
74+
75+
- learning-oriented *tutorials*
76+
- problem-oriented *how-to guides*
77+
- understanding-oriented *explanations*
78+
- information-oriented *technical reference*
79+
80+
![](https://documentation.divio.com/_images/overview.png)
81+
82+
### The project’s scope
83+
84+
The GeomScale project will:
85+
86+
- Audit and collect the existing tutorials currently distributed in blogs, wiki pages and presentations and create a friction log.
87+
- Using the friction log as a guide for understanding the gaps in the currently fragmented tutorials.
88+
- Write new tutorials that highlight the usage of GeomScale tools in various applications such as biology and computational finance and statistics. The set of tutorials should range from simple intoductory ones to advanced one that provide solution to spesific applications. See [this example](https://colab.research.google.com/github/GeomScale/dingo/blob/develop/tutorials/dingo_tutorial.ipynb).
89+
- Incorporate feedback from tutorial testers (volunteers in the project) and the wider GeomScale community.
90+
- Collaborate with GeomScale project administrators to select how tutorials should be sructures and presented.
91+
92+
Work that is out-of-scope for this project:
93+
94+
- This project will not create any explanation, rerefence documentationa or how-to guides.
95+
96+
97+
## Measuring your project’s success
98+
99+
GeomScale receives an average of 10 pull requests a quarter to add a new feature or optimization or propose a bug fix.
100+
Many of these pull requests are from previous contributors.
101+
We believe that new tutorials will result in more pull requests and more pull requests from new contributors.
102+
103+
We will track three metrics:
104+
(a) number of new feature pull requests,
105+
(b) number of pull requests from new contributors,
106+
(c) standard metrics (number of views, downloads, web traffic to GeomScale site, time on page),
107+
monthly after the documentation is published. We will also track the number
108+
of contributors who have made more than three contributions overall,
109+
starting quarterly after the documentation is published.
110+
111+
We would consider the project successful if, after publication of the new documentation at least three of the following hold:
112+
- The number of new feature pull requests increases by 10%
113+
- The number of pull requests from new contributors increases by 15%
114+
- The number of contributors who have made >2 contributions increases by 5% (beginning the quarter after the documentation is published)
115+
- The standard metrics increased by 10% on average
116+
- The number of forks and stars in our repository increased by 10%
117+
118+
## Project budget
119+
120+
| Budget item | Amount | Running Total | Notes/justifications |
121+
|---|---|---|---|
122+
| Technical writer audit, update, test, and publish reference documentation of GeomScale project | 13000.00 | 13000.00 | |
123+
| Volunteer stipends | 500 | 14500.00 | 3 volunteer stipends x 500 each |
124+
| TOTAL | | 14500.00 | |
125+
126+
127+
## Additional information
128+
129+
### Previous experience with technical writers or documentation:
130+
131+
GeomScale has succeffully participated in GSoD 2022 where volesti's documentation [website](https://volesti.readthedocs.io/) was built (using doxygen, Sphynx and ReadTheDocs tech stack) and a basic reference documentation was written!
132+
133+
Apart from GSoD participation, members of GeomScale have experience in developing and reviewing documentation.
134+
For example in developing and mentoring documentation development
135+
for [`R` CRAN package volesti](https://CRAN.R-project.org/package=volesti).
136+
The review process used was similar to a coding review. Examples of documentation
137+
review process in GeomScale are available from
138+
[github](https://github.com/boostorg/geometry/pulls?q=is%3Apr+is%3Aclosed+label%3Adocumentation).
139+
In addition to this we usually employ a last step of iterating the final draft
140+
of documentation to our peers and users for feedback.
141+
142+
Our previous experience with documentation development gives us confidence to
143+
apply best practices and well established review processes and tools to the
144+
potential GSoD projects. For example, the GSoD project development will take
145+
part in github by opening issues for discussion and pull requests
146+
(with a documentation tab) to submit/review the technical writer's contributions.
147+
148+
### Previous participation in Season of Docs, Google Summer of Code or others:
149+
150+
All the members of GeomScale have previously participated in Google Summer of
151+
Code as mentors or/and as students. Our members have mentored 7 GSoC coding
152+
projects under `R`-project and Boost `C++` libraries organizations (2017-2019).
153+
The main software package of GeomScale has been substantially enhanced through
154+
3 GSoC projects under the mentoring of two of GeomScale’s members, while one
155+
student of those projects (Apostolos Chalkis) became a GeomScale member and
156+
GSoC mentor and admin.
157+
158+
The last four years (2020-2023) GeomScale has been selected as a mentoring
159+
organization for GSoC. In 2021 we have successfully mentored 6 projects
160+
resulting in >9 pull requests 6 of which are merged into our repositories
161+
development branch.
162+
163+
We strongly believe that this experience will play a crucial role for
164+
successful GSoD projects. In particular, we have experience in communicating
165+
with persons of diverged educational and cultural background and focused
166+
to give the right tips and guidance for successful projects. Moreover,
167+
we are capable of fixing detailed and realistic time schedules based on
168+
the technical writer’s profile and potential.

0 commit comments

Comments
 (0)