From 81864b9bd538df5b6e19e5074df68a4c61fe7c9c Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sun, 3 May 2020 20:42:44 -0500 Subject: [PATCH] blog: rewrite project ideas after feedback from Ivan --- content/blog/2020-04-30-gsod-ideas-2020.md | 90 ++++++++++++++++------ 1 file changed, 65 insertions(+), 25 deletions(-) diff --git a/content/blog/2020-04-30-gsod-ideas-2020.md b/content/blog/2020-04-30-gsod-ideas-2020.md index 6ec1553c515..922f92f6336 100644 --- a/content/blog/2020-04-30-gsod-ideas-2020.md +++ b/content/blog/2020-04-30-gsod-ideas-2020.md @@ -5,18 +5,15 @@ 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 Code 2020](https://developers.google.com/season-of-docs). + [Google Season of Docs 2020](https://developers.google.com/season-of-docs). picture: 2019-04-23/post-image.png pictureComment: author: jorge_orpinel -commentsUrl: +commentsUrl: https://discuss.dvc.org/t/join-dvc-for-google-season-of-docs-2020/375 tags: - Google Season of Docs - - Technical Writers - Documentation - Mentoring - - Open source - - Writers --- Exciting announcement! After a successful experience with @@ -26,6 +23,11 @@ we're putting out a call for writers to apply to work with DVC as part of the involved with 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. + ## Prerequisites to apply Besides the general requirements to apply to Google Season of Docs, there are a @@ -55,35 +57,73 @@ 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). -1. **How-to section.** We have compiles a - [set of topics](https://github.com/iterative/dvc.org/issues/899) that we - think would be best explained in a new "How to" section of our docs. This - will imply relocating bits and pieces of info from existing docs into new - how-tos, as well as writing significant new material to complete them. +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! _Difficulty rating:_ Beginner-Medium

-1. **Tutorials to Blog.** DVC is currently rewriting it's main tutorial, the - [Get Started](https://github.com/iterative/dvc.org/pull/1074). The remaining - [Tutorials](https://dvc.org/doc/tutorials) will then become somewhat - redundant so we are considering moving them out of the docs and into blog - posts instead. Other possible rearrangements of the tutorials may end up - being preferred. +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 + 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). + + **Mentor**: [Elle](https://github.com/andronovhopf) + + _Difficulty rating:_ Medium

- _Difficulty rating:_ Medium-Advanced

+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 + to be able to follow by copying commands into their terminals. This has a few + challenges: mainly keeping the rest of the document maintainable, brief, and + easy to read; and supporting people on all platforms (Mac, Windows, Linux). -1. **Integrate interactive guides.** We have a set of - [Katacoda scenarios](https://www.katacoda.com/dvc) to match different - sections of our docs. These need to be checked and updated, as well as + So we started extracting some of the command examples into interactive + [Katacoda scenarios](https://www.katacoda.com/dvc) to match certain docs, + however they are in need of maintenance and completion, as well as being embedded into the corresponding pages per - [this issue](https://github.com/iterative/dvc.org/issues/670). This would - involve working with our front-end team or, preferably, having some + [this issue](https://github.com/iterative/dvc.org/issues/670). + + This may involve working with our front-end team or, preferably, having some Javascript coding experience. - _Difficulty rating:_ Advanced + _Difficulty rating:_ Medium-Advanced + +1. **Javascript engine UI/UX.** Our website has custom + + [source code](https://github.com/iterative/dvc.org/tree/master/src) we've + 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 + + - 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. + + _Difficulty rating:_ Advanced

-> For more inspiration, feel free to review our open -> [documentation issues](https://github.com/iterative/dvc.org/issues?q=is%3Aopen+is%3Aissue+label%3Adoc-content+). +> For more inspiration, feel free to review our +> [epics](https://github.com/iterative/dvc.org/labels/epic) and other open docs +> [issues](https://github.com/iterative/dvc.org/issues?q=is%3Aopen+is%3Aissue+label%3Adoc-content+). ## If you'd like to apply