We strongly believe that well-shaped documentation is key for making the product\ntruly open. We have been investing lots of time and energy…
","html":"We strongly believe that well-shaped documentation is key for making the product\ntruly open. We have been investing lots of time and energy in improving our docs\nlately. Being a team of 90% engineers we are eager to welcome the writers into\nour team and our community. We are happy to share our experience, introduce them\nto the world of open source and machine learning best practices, guide through\nthe OS contribution process and work together on improving our documentation.
\nDVC was started in late 2017 by a data scientist and an engineer. It is now\ngrowing pretty fast and though our in-house team is quite small, we have to\nthank our contributors (more than 80 in both code and docs) for developing DVC\nwith us. When working with DVC the technical writer will not only get lots of\nhands-on experience in writing technical docs, but will also immerse into DVC\ncommunity — a warm and welcoming gathering of ML and DS enthusiasts and an\ninvaluable source of inspiration and expertise in ML engineering.
\nDVC is a brainchild of a data scientist and an engineer, that was created to\nfill in the gaps in the ML processes tooling and evolved into a successful open\nsource project.
\nML brings changes in development and research processes. These ML processes\nrequire new tools for data versioning, ML pipeline versioning, resource\nmanagement for model training and others that haven’t been formalized. The\ntraditional software development tools do not fully cover ML team’s needs but\nthere are no good alternatives. It makes engineers to custom develop a new\ntoolset to manage data files, keep track of ML experiments and connect data and\nsource code together. The ML process becomes very fragile and requires tons of\ntribal knowledge.
\nWe have been working on DVC by adopting best ML practices and\nturning them into Git-like command line tool. DVC versions multi-gigabyte\ndatasets and ML models, make them shareable and reproducible. The tool helps to\norganize a more rigorous process around datasets and the data derivatives. Your\nfavorite cloud storage (S3, GCS, or bare metal SSH server) could be used with\nDVC as a data file backend.
\nIf you are interested in learning a little bit more about DVC and its journey,\nhere is a great interview with DVC creator in the Episode 206 of\nPodcast.init. Listen to it\nHERE or read\nthe transcript\nHERE.
\nDVC is a pretty young project, developed and maintained solely by engineers. As\nmany OS projects we started from the bottom and for a long time our\ndocumentation was a bunch of bits and pieces. Nowadays\nimproving documentation is one of our top priorities. We moved to the new\nin-house built documentation engine and started working with several technical\nwriters. Certain parts have been tremendously improved recently, e.g.\nGet Started and\ncertain parts of Commands Reference\n. So far most of our documentation has been written majorly by the engineering\nteam and there is need for improving the overall structure and making some parts\nmore friendly from a new user perspective. We have mostly complete\nreference documentation for each\ncommand, although some functions are missing good actionable examples. We also\nhave a User Guide,\nhowever it is not in very good shape. We strive for making our documentation\nclear and comprehensive for users of various backgrounds and proficiency levels\nand this is where we do need some fresh perspective.
\nWe have an open Github Apache-2 licensed repository for the\nDVC website, the documentation engine\nand the documentation files. The website\nis built with Node.js + React, including the documentation engine (built\nin-house).
\nEach documentation page is a static Markdown file in the repository, e.g.\nexample here.\nIt is rendered dynamically in the browser, no preprocessing is required. It\nmeans that tech writers or contributors need to write/edit a Markdown file,\ncreate a pull request and merge it into the master branch of the\nrepository. The complete\ndocumentation contributing guide\ndescribes the directory structure and locations for the different documentation\nparts.
\nDocumentation tasks and issues are maintained on our doc’s GitHub\nissue tracker. Changes to the\ndocumentation are made via pull requests on GitHub, and go through our standard\nreview process which is the same for documentation and code. A technical writer\nwould be trained in working with our current development process. It generally\nmeans that tech writers or contributors need to write/edit a Markdown file, use\ngit and Github to create a pull request and publish it. The documentation\ncontributing guide\nincludes style conventions and other details. Documentation is considered of the\nsame importance as code. Engineering team has a policy to write or update the\nrelevant sections if something new is released. If it’s something too involved\nengineers may create a ticket and ask for help. There is one maintainer who is\nresponsible for doing final reviews and merging the changes. In this sense, our\ndocumentation is very similar to any other open source project.
\nWe identified a number of ideas to work on and there are two major topics these\nideas fall into. Both topics are pretty broad and we don’t expect we can\ncompletely cover them during this GSoD but hopefully we can make certain\nprogress.
\nFirst of all, we want to bring more structure and logic to our documentation to\nimprove user onboarding experience. The goal is for a new user to have a clear\npath they can follow and understand what takeaways each part of the\ndocumentation provides. In particular, improving how\nGet Started,\nTutorials and\nExamples relate to each\nother, restructuring the existing User Guide\nto explain basic concepts, and writing more use cases that resonate with ML\nengineers and data scientists.
\nThe other issue we would like to tackle is improving and expanding the existing\nreference docs — commands descriptions, examples, etc. It involves filling in\nthe gaps and developing new sections, similar to\nthis one. We would also love to\nsee more illustrative materials.
\nDescription and details: Reviewing, restructuring and filling major gaps in\nthe User Guide (introductory parts of the basic concepts of DVC), e.g. have a\nlook at this ticket or\nthis one.
\nMentors: @shcheklein and\n@dmpetrov
\nDescription and details: We already have some requests for more tutorials,\ne.g. this ticket. Here is\nanother good use case request\n. If you are going to work on this project you would need some domain knowledge,\npreferably some basic ML or data science experience.
\nMentors: @shcheklein and\n@dmpetrov
\nDescription and details: Analyze and restructure user walkthrough across\nGet started,\nTutorials and\nExamples. These three have\none thing in common — hands-on experience with DVC. If you choose this project,\nwe will work together to come up with a better location for the Examples (to\nmove them out of the Get Started shadow), and a better location for the\nTutorials (to reference external tutorials that were developed by our community\nmembers and published on different platforms).
\nMentors: @shcheklein and\n@dmpetrov
\nDescription and details: We will work on improving our\nCommands reference section. This\nincludes expanding and filling in the gaps. One of the biggest pain points right\nnow are Examples. Users want them to be\neasy to run and try and here\nis a lot to be done in terms of improvement. We have a good example of how is\nshould be done here.
\nMentors: @shcheklein and\n@dmpetrov
\nDescription and details: Describe the brand new feature “DVC packages” and\nintegrate it with the rest of the documentation. We have been working hard to\nrelease a few new commands to help with datasets management (have a look at\nthis ticket). It’s a major\nfeature that deserves its place in the Get Started, Use cases, Commands\nReference, etc.
\nMentors: @shcheklein and\n@dmpetrov
\nThe ideas we outline above are just an example of what we can work on. We are\nopen for any other suggestions and would like to work together with the\ntechnical writer to make the contribution experience both useful and enjoyable\nfor all parties involved. If you have any suggestions or questions we would love\nto hear from you => DVC.org/support and our DMs on\nTwitter are always open!
\nSpecial thanks to the NumFOCUS for the ideas list\ninspiration.
\nIf you are a tech writer — check the\nTechnical writer guide.\nFrom April 30, 2019 you can see the list of participating open source\norganizations on the Season of Docs website. The\napplication period for technical writers opens on May 29, 2019 and ends on\nJune 28, 2019.
","timeToRead":8,"fields":{"slug":"/dvc-project-ideas-for-google-summer-of-docs-2019"},"frontmatter":{"title":"DVC project ideas for Google Season of Docs 2019","date":"April 23, 2019","description":"DVC.org is applying for Google Season of Docs — a new and unique program\nsponsored by Google that pairs technical writers with open source projects to\ncollaborate on the open source project documentation.\n","descriptionLong":"DVC.org is applying for Google Season of Docs — a new and unique program\nsponsored by Google that pairs technical writers with open source projects to\ncollaborate on the open source project documentation. It’s happening for the\nfirst time in 2019 and we are excited about the opportunity to be a part of\nit!\n","tags":["Google Season of Docs","Python","Documentation","DVC"],"commentsUrl":"https://discuss.dvc.org/t/dvc-project-ideas-for-google-season-of-docs-2019/291","author":{"childMarkdownRemark":{"frontmatter":{"name":"Svetlana Grinchenko","avatar":{"childImageSharp":{"fixed":{"base64":"data:image/jpeg;base64,/9j/2wBDABALDA4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVGC8aGi9jQjhCY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2P/wgARCAAUABQDASIAAhEBAxEB/8QAGAABAAMBAAAAAAAAAAAAAAAAAAIDBQT/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIQAxAAAAHRz7x3qhnQCoH/xAAaEAACAwEBAAAAAAAAAAAAAAABAgMEMxIU/9oACAEBAAEFArBJZ0aqyN0s+trCvhYchTKzj0SRD//EABQRAQAAAAAAAAAAAAAAAAAAACD/2gAIAQMBAT8BH//EABQRAQAAAAAAAAAAAAAAAAAAACD/2gAIAQIBAT8BH//EAB0QAAICAgMBAAAAAAAAAAAAAAECABExQQMSIVH/2gAIAQEABj8CXiVuvbcDK9jYMDDcRyLBFTHpIixRflQjAHyBVwJ//8QAGxABAAMAAwEAAAAAAAAAAAAAAQARQSExUXH/2gAIAQEAAT8ht1LLoIkF4B6wLgOVH8uRVjiTT5AoqBr2L1odagwijiyf/9oADAMBAAIAAwAAABBjDwD/xAAUEQEAAAAAAAAAAAAAAAAAAAAg/9oACAEDAQE/EB//xAAUEQEAAAAAAAAAAAAAAAAAAAAg/9oACAECAQE/EB//xAAeEAACAwADAAMAAAAAAAAAAAABEQAhMUFRYXGBkf/aAAgBAQABPxCmAzsDr5hIjqwzzzqjPahi5r8IQVrj2MCG47GtJ+o5KCJ7t+zbocIBE8rYP/mqRYTv5EF8QZIHU//Z","width":40,"height":40,"src":"/static/fcc8502faa36f9a989fa0651c3c21653/d83e5/svetlana_grinchenko.jpg","srcSet":"/static/fcc8502faa36f9a989fa0651c3c21653/d83e5/svetlana_grinchenko.jpg 1x,\n/static/fcc8502faa36f9a989fa0651c3c21653/58860/svetlana_grinchenko.jpg 1.5x,\n/static/fcc8502faa36f9a989fa0651c3c21653/90ac5/svetlana_grinchenko.jpg 2x","srcWebp":"/static/fcc8502faa36f9a989fa0651c3c21653/e145b/svetlana_grinchenko.webp","srcSetWebp":"/static/fcc8502faa36f9a989fa0651c3c21653/e145b/svetlana_grinchenko.webp 1x,\n/static/fcc8502faa36f9a989fa0651c3c21653/0d42c/svetlana_grinchenko.webp 1.5x,\n/static/fcc8502faa36f9a989fa0651c3c21653/f46db/svetlana_grinchenko.webp 2x"}}}}}},"picture":{"childImageSharp":{"fluid":{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAPCAIAAABr+ngCAAAACXBIWXMAAAsSAAALEgHS3X78AAADUUlEQVQoz3WRy28TVxjFbwhINIRXFVO6Adp/gQWIBbugdtlm0VaqSIOSCLAQCEGkRASCSsOCpi2Ulqig4jgQGzuQMH6NnThjJ3ZIkxm/Z2x3HL8ytuOMJ6SyPQ+PH50J6qILjn469yGd+937XcAfVch8fFCEtZWSi43+WgrdLoVuvaMsc3Pb5WUxeFNIqevCekNWDfBH2rhjh0TFnvVvPl+2arDpMcw4gRo0XoPGY9RgRg1qfIFCExKYtGnRLuqfUu4fGyxZFxjAH94n5SXYI4dI9ZR/ORGcC4Tf4G/cfq/Th8/7ozPOOBZM+ongfMhjC9q0Ae/0vWrqt4r/AhCHh/gDu6TilcOtW6dP4sFV/2oug0f+sLtH4OWE7tna5Fg6EEygPsIbDSey89aAz/Sk6uvgIQCku4v3hoX9O/ljioqi5Z+vv4iu57JbxSdL+I3pxZX7D2ibNhqKedBY0EcmqZzLQeG6noa9STA1gUatJuX5h/fLilbho71C2+6tM2e2fvoeefUQXfk7shQmnY44kUC9zAq2KT0kbenlDDsq5iYJUK/XpXBug/3rzu9C+wnuw4PCqQ+qQ4B/CSJwdwxWbUAjOWySIsZp9HLZ/knVBETL/8PZRAExY/kYuTnYI/Tu5I4rKl/uq9oANwUEQ5Ng3lExgioEJOfNuwRTs2gG0in/VU6/XXjpKCTThYiqNgsqn7WKu/eKP7TVXC0NC5CBQR2W/d2ENzeXZj4F29/diOhn4D9nIy6Pz+ql59rFwT1UewehNYWRKdJyN264knjdlXh9NmnsJXSX5nXDVpvesEDI4YgGutX9aFCp7leq+pVjQ8pf7py93df7uK9ntK9z9HqX6vo5dd85lcQ1ia6x/u7xx+NenTMOisgc+d15590u5NFX0z1Kfedl04Nxuw11WBcd8CJilXAjsMsKITCEOK3uV3r7z6Mm7Wz4xRwJMjcGkhevrqu7uUAnrR5gUH+MxKlMKr2WzOWzVHatWCpmstRGIU8zG/l8ZjlAqqAl7Qw+6VwFKeXF1IVLqwPfxp91FhlCqDfogiyalsfNzbccyzEMw/MCWy6nqbza6HkKYc9txMQsCdhQiMVxzh8QU2ty67ab/z6xfDVTYLMMlymUM3TpXwMGgA/YGuToAAAAAElFTkSuQmCC","aspectRatio":1.34715821812596,"src":"/static/3f83b2f133ac48de03c7aa1b31e399d4/286b3/post-image.png","srcSet":"/static/3f83b2f133ac48de03c7aa1b31e399d4/1f44b/post-image.png 213w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/3e433/post-image.png 425w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/286b3/post-image.png 850w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/9a739/post-image.png 1275w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/c47cc/post-image.png 1700w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/fee50/post-image.png 1754w","srcWebp":"/static/3f83b2f133ac48de03c7aa1b31e399d4/5c1d9/post-image.webp","srcSetWebp":"/static/3f83b2f133ac48de03c7aa1b31e399d4/99b2d/post-image.webp 213w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/23220/post-image.webp 425w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/5c1d9/post-image.webp 850w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/5e720/post-image.webp 1275w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/35cfd/post-image.webp 1700w,\n/static/3f83b2f133ac48de03c7aa1b31e399d4/cf3ed/post-image.webp 1754w","sizes":"(max-width: 850px) 100vw, 850px","presentationWidth":850}}},"pictureComment":null}}},"pageContext":{"next":{"fields":{"slug":"/may-19-dvc-heartbeat"},"frontmatter":{"title":"May ’19 DVC❤️Heartbeat"}},"previous":{"fields":{"slug":"/april-19-dvc-heartbeat"},"frontmatter":{"title":"April ’19 DVC❤️Heartbeat"}},"currentPage":12,"slug":"/dvc-project-ideas-for-google-summer-of-docs-2019"}}}