Merge pull request #1233 from iterative/gsod

blog: GSoD 2020 post improvements

content/blog/2019-09-26-september-19-dvc-heartbeat.md

@@ -59,7 +59,7 @@ Some other highlights of the end of summer:
   [DVC documentation](https://github.com/iterative/dvc.org) (and have something
   special in mind to celebrate our 100th contributors).
 
-- we enjoyed working with all the talented
+- We enjoyed working with all the talented
   [Google Season of docs](https://developers.google.com/season-of-docs/)
   applicants and now moving to the next stage with our chosen tech writer
   [Dashamir Hoxha](http://dashohoxha.fs.al/).

content/blog/2019-11-05-october-19-dvc-heartbeat.md

@@ -45,8 +45,8 @@ it this year. Here are some of the highlights:
   or
   [this tutorial in German](https://jupyter-tutorial.readthedocs.io/de/latest/productive/dvc/)!
 
-- Having great time working with a [tech writer](https://github.com/dashohoxha)
-  brought to us by the
+- Having a great time working with a
+  [tech writer](https://github.com/dashohoxha) brought to us by the
   [Google Season of Docs](https://developers.google.com/season-of-docs) program.
   Check out these
   [interactive tutorials](https://dvc.org/doc/tutorials/interactive) we’ve

content/blog/2020-04-30-gsod-ideas-2020.md

@@ -4,8 +4,11 @@ date: 2020-04-30
 description: |
   A call for writer applications for Google Season of Docs 2020.
 descriptionLong: |
-  DVC is looking for writers to take part in
-  [Google Season of Docs 2020](https://developers.google.com/season-of-docs).
+  DVC is looking for technical writers to take part in
+  [Google Season of Docs 2020](https://developers.google.com/season-of-docs) —
+  a unique program sponsored by Google that pairs technical writers with open
+  source projects. In this post we introduce our goals for the program, and
+  specific [project ideas](#project-ideas) for potential candidates.
 picture: 2019-04-23/post-image.png
 pictureComment:
 author: jorge_orpinel
@@ -16,17 +19,71 @@ tags:
   - Mentoring
 ---
 
-Exciting announcement! After a successful experience with
-[Google Season of Docs](https://developers.google.com/season-of-docs) 2019,
-we're putting out a call for writers to apply to work with DVC as part of the
-[2020 edition](https://developers.google.com/season-of-docs). If you want to get
-involved with open source software documentation with mentorship from our team,
-read on.
+After a successful experience with the first edition of **Google Season of
+Docs** [in 2019](/blog/dvc-project-ideas-for-google-summer-of-docs-2019), we're
+putting out a call for writers to apply to work with DVC as part of the
+[2020 edition](https://developers.google.com/season-of-docs). If you want to
+write open source software documentation with mentorship from our team, read on.
 
-DVC has a well organized docs team and a
-[well-defined process](https://dvc.org/doc/user-guide/contributing/docs) for
-creating and maintaining our documentation, while working closely with the core
-engineering team.
+**TLDR**: Skip to [project ideas](#project-ideas).
+
+[DVC](https://dvc.org/) has a dedicated docs team and a
+[well-defined process](/doc/user-guide/contributing/docs) for creating and
+maintaining our documentation, modeled in part based on our past GSoD
+experience. We are happy to share our experience, introduce technical writers to
+the world of open source and machine learning best practices, and work together
+on improving our documentation.
+
+## Previous experience
+
+In last year's Season, we matched with prolific writer
+[Dashamir](https://github.com/dashohoxha), who helped us give proper structure
+important part of our docs, and address key issues.
+
+https://twitter.com/DVCorg/status/1205203662827483136
+
+Some of our achievements together were:
+
+- Reorganized our [tutorials](https://github.com/iterative/dvc.org/pull/666) and
+  core [contribution guide](https://github.com/iterative/dvc.org/pull/726)
+- Created [interactive lessons](https://github.com/iterative/dvc.org/issues/546)
+  on [Katacoda](https://www.katacoda.com/dvc)
+- Docs [cleanup](https://github.com/iterative/dvc.org/pull/734)
+- Suggested the creation of a
+  [How To](https://github.com/iterative/dvc.org/issues/563) section for our docs
+- Other
+  [contributions](https://github.com/iterative/dvc.org/pulls?q=is%3Apr+is%3Aclosed+author%3Adashohoxha)
+
+Another collaborator we connected with via GSoD’19 was an amazing student
+intern, [Aman](https://github.com/algomaster99). He helped us address
+[dozens of tickets](https://github.com/iterative/dvc.org/pulls?q=is%3Apr+author%3Aalgomaster99+is%3Aclosed)
+related to our Node.js docs web app. For example:
+
+- Contributed to our
+  [command reference](https://github.com/iterative/dvc.org/pull/315) and
+  [user guide](https://github.com/iterative/dvc.org/pull/366), and created a
+  much needed
+  [documentation contribution](https://github.com/iterative/dvc.org/pull/317)
+  guide
+
+- [Formatted](https://github.com/iterative/dvc.org/pull/328) the source code of
+  our docs and established an
+  [automated mechanism](https://github.com/iterative/dvc.org/pull/386) to
+  enforce pretty formatting going forward
+
+- Implemented super useful hovering tooltips based on a special
+  [glossary](https://github.com/iterative/dvc.org/pull/431)
+
+  ![](/uploads/images/2020-04-30/tooltip.png) _From the `dvc remote` command
+  reference_
+
+Another positive result of the program was that our open source collaborators
+organized talks and meetups with our mentorship:
+
+![](/uploads/images/2020-04-30/SciPy_India_Aman.png) _Our intern Aman took a
+several-hour long train ride to
+[talk](https://static.fossee.in/scipy2019/SciPyTalks/SciPyIndia2019%5FS011%5FStoring%5Fa%5Ffew%5Fversions%5Fof%5Fa%5F5GB%5Ffile%5Fin%5Fa%5Fdata%5Fscience%5Fproject%5F20191130.mp4)
+at [SciPy India 2019](https://scipy.in/2019)._
 
 ## Prerequisites to apply
 
@@ -36,12 +93,12 @@ few skills we look for in applicants.
 1. **Clear English writing.** We strive express the concepts, processes, and
    details around DVC clearly, correctly, and completely. We use general and
    friendly wording as much as possible and pay close attention to consistency
-   in our terminology.
+   in our terminology. Our team will help with copy editing.
 
 1. **Command line experience.** [DVC](/doc/home) is a command line tool that
    builds on top of [Git](https://git-scm.com/), so being able to play with it
    and test the features will be very useful. Creating and managing files,
-   GNU/Linux commands, file and permission admin are desired skills.
+   GNU/Linux commands, file and permission administration are desired skills.
 
 1. **People skills.** We put a high value on communication: the ability to
    discuss ideas, explain your goals, report progress, and work kindly with more
@@ -53,33 +110,59 @@ be in touch anyway. We'd love to hear from you.
 ## Project ideas
 
 Below are several project ideas that are an immediate priority for the DVC docs
-team. We welcome writers to create their own proposals, even if they differ from
-our ideas. Projects will be primarily mentored by our lead technical writer,
-[Jorge](https://github.com/jorgeorpinel).
+team. We welcome technical writers to create their own proposals, even if they
+differ from our ideas. Most projects will be mentored primarily by our lead
+technical writer, [Jorge](https://github.com/jorgeorpinel).
+
+1. **"How To" section.** Other than our
+   [use cases](https://dvc.org/doc/use-cases), we still lack a good place to
+   answer common questions in our docs (think FAQ). We have compiled
+   [set of topics](https://github.com/iterative/dvc.org/issues/899) that we
+   think would be best explained in a new **How To** section for this purpose.
+
+   This project would imply relocating bits and pieces of info from existing
+   docs into new how-tos, as well as writing significant new material to
+   complete them. Expanding on our
+   [troubleshooting](https://dvc.org/doc/user-guide/troubleshooting) page would
+   probably go well as part of this project as well.
+
+   _Difficulty rating:_ Beginner-Medium<br/><br/>
 
 1. **DVC 1.0 docs.** We are soon to release DVC 1.0.0! This version brings some
    significant changes that for the first time in our
    [release history](https://github.com/iterative/dvc/releases) are not
-   completely backward-compatible. The main change is a multi-stage _pipelines
-   file_ that substitutes
-   [DVC-files](https://dvc.org/doc/user-guide/dvc-file-format). We expect the
-   process to fully update all our previous docs will take a few months, and you
-   could help us with this!
+   completely backward-compatible. We expect that fully updating all our
+   previous docs will take a few months, and you could help us with this! The
+   main new features are:
+
+   - A
+     [multi-stage _pipelines file_](https://github.com/iterative/dvc/issues/1871)
+     that partially substitutes
+     [DVC-files](https://dvc.org/doc/user-guide/dvc-file-format)
+   - Separation between
+     [scalar vs. continuous metrics](https://github.com/iterative/dvc/issues/3409),
+     and new commands to visualize them, such as `dvc plot`
+   - A new [run cache](https://github.com/iterative/dvc/issues/1234) that
+     automatically saves experiment checkpoints between commits
 
    _Difficulty rating:_ Beginner-Medium<br/><br/>
 
 1. **Video tutorials.** Written documentation is great, but other media can also
    be important for our organization to reach a wide variety of learners.
    Expanding to video is also a core part of our developer advocacy strategy.
-   One of DVC's priorities for the season is creating a library of video
+
+   One of DVC's priorities for this year is creating a library of video
    tutorials ranging from short explanations of basic DVC functions to more
    advanced use cases. You could assist in writing the scripts or even take the
    lead producing some videos, so image/video editing skills would come in handy
-   (optional).
+   (optional). For inspiration, here's a fun intro to DVC video we produced some
+   time ago:
+
+   https://www.youtube.com/watch?v=4h6I9_xeYA4
 
    **Mentor**: [Elle](https://github.com/andronovhopf)
 
-   _Difficulty rating:_ Medium<br/><br/>
+   _Difficulty rating:_ Beginner-Medium<br/><br/>
 
 1. **Interactive guides.** Many of our docs include command line examples to
    illustrate how DVC works. In some cases these are full guides we want people
@@ -103,20 +186,19 @@ our ideas. Projects will be primarily mentored by our lead technical writer,
    developed over the years to host our landing pages, docs, and blog all in a
    high-performance, advanced static site (Node.js, Gatsby, React, Typescript).
    We have several goals to further improve the usability and structure of our
-   site, such as
+   site, such as:
 
-   - creating a
-     [special docs home page](https://github.com/iterative/dvc.org/issues/1073).
-   - improving [mobile menus](https://github.com/iterative/dvc.org/issues/808).
-   - better navigation sidebar
+   - Creating a
+     [special docs home page](https://github.com/iterative/dvc.org/issues/1073)
+   - Improving [mobile menus](https://github.com/iterative/dvc.org/issues/808)
+   - Better navigation sidebar
      [highlighting](https://github.com/iterative/dvc.org/issues/753) and
-     [positioning](https://github.com/iterative/dvc.org/issues/1198).
-
-   > See other
-   > [doc-engine](https://github.com/iterative/dvc.org/issues?q=is%3Aopen+is%3Aissue+label%3Adoc-engine)
-   > and
-   > [blog-engine](https://github.com/iterative/dvc.org/issues?q=is%3Aopen+is%3Aissue+label%3Ablog-engine)
-   > issues.
+     [positioning](https://github.com/iterative/dvc.org/issues/1198)
+   - Other
+     [doc-engine](https://github.com/iterative/dvc.org/issues?q=is%3Aopen+is%3Aissue+label%3Adoc-engine)
+     and
+     [blog-engine](https://github.com/iterative/dvc.org/issues?q=is%3Aopen+is%3Aissue+label%3Ablog-engine)
+     issues
 
    _Difficulty rating:_ Advanced<br/><br/>