# Restructuring docs **URL:** \ **Category:** Development\ **Created:** [August 20, 2019, 10:28am UTC](https://discuss.dvc.org/t/restructuring-docs/201 "2019-08-20T10:28:59Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![dashohoxha](https://yyz1.discourse-cdn.com/flex035/user_avatar/discuss.dvc.org/dashohoxha/32/45_2.png) [@dashohoxha](https://discuss.dvc.org/u/dashohoxha)\ **Post date:** [August 20, 2019, 10:28am UTC](https://discuss.dvc.org/t/restructuring-docs/201/1 "2019-08-20T10:28:59Z")
It is obvious that the structure of the docs needs some revising, but it is not so clear what the best structure would be. I would try these things: 1. Create a top level section for “Contributor Guide” or “Developer Guide” and move there the sections: 2. Move “Use Cases” inside the “User Guide”. I think that these “use cases” are actually useful for helping or guiding the user on how to use properly DVC, so they should a part of the User Guide. If the term “use case” sounds a bit technical (and it is actually a bit overloaded with other meanings), they may be called “Configuration Examples” or “Usage Examples”. But the term “Use Cases” is fine too. 3. Create a separate section for the tutorials and move there the examples at the of “Get Started”. Move inside it the “Tutorial” a well. Actually there is some overlap among the tutorials and some parts of them need to be updated (because the code does not work as expected). So, they need to be cleaned up and updated. Other tutorials may be added by adopting blog posts about DVC or adapting blog posts about DS/ML in general. 4. “Installation” should be a top level and separate section, placed before the “Tutorials”. 5. The “Get Started” part should be simplified further from some detailed/advanced explanations and from links/references to more advanced sections. Actually, it can also be replaced by a set of Katacoda interactive tutorials, which should be very basic, hands-on and learn-by-doing style ([https://github.com/iterative/dvc.org/issues/546](https://github.com/iterative/dvc.org/issues/546)). 6. The sections inside the “User Guide” need to be restructured, rearranged or expanded. For example see these discussions: One thing that I would like to note is that the Waterfall process does not seem to work well with the docs too (same as with software development and DS/ML development). So, we should not aim for a perfect plan and execution, but let’s start by doing and experimenting, and then correcting and fixing and reverting (if necessary), until the docs seem to be in a good shape. During my GSoD period I may not be able to finish all of these, but I may try to do as much as possible. I would like to try them in this order: 1. Build a set of basic interactive tutorials with Katacoda. 2. Separate the installation page and simplify the Get Started tutorial. 3. Fix the general structure of the docs (merge Use Cases with the User Guide, separate Contributor Guide from User Guide, make a section for the Tutorials, etc.) 4. Work on cleaning up and improving the “external-data” of the User Guide and its related use-cases. 5. Work on deduplicating and updating the existing tutorials. 6. Add more use-cases and tutorials. 7. Update the pages of the commands to refer to the appropriate tutorials (or interactive tutorials in Katacoda). 8 . Try to describe and integrate “DVC packages” on the docs. Please let me know if you have any comments or suggestions. ---
**Author:** ![shcheklein](https://yyz1.discourse-cdn.com/flex035/user_avatar/discuss.dvc.org/shcheklein/32/173_2.png) [@shcheklein](https://discuss.dvc.org/u/shcheklein)\ **Post date:** [September 6, 2019, 7:35pm UTC](https://discuss.dvc.org/t/restructuring-docs/201/2 "2019-09-06T19:35:00Z")
Hi, @dashohoxha! Great summary, thank you! I would suggest that we start with the User Guide and Understanding DVC refactoring as we discussed - there are tickets for this I believe. Re the top level sections. For each of them, I would start by creating a second level section in the User Guide first. Then we will decide which of them it makes sense to move to the top level. Please, use Github and split the plan into some manageable issues/tickets. It’s very hard to discuss and give feedback on 6 large items at once. It’s not good to have two places for this kind of discussions. ---
**Author:** ![dashohoxha](https://yyz1.discourse-cdn.com/flex035/user_avatar/discuss.dvc.org/dashohoxha/32/45_2.png) [@dashohoxha](https://discuss.dvc.org/u/dashohoxha)\ **Post date:** [September 6, 2019, 8:18pm UTC](https://discuss.dvc.org/t/restructuring-docs/201/3 "2019-09-06T20:18:26Z")
I have already started with Katakoda, but it is still WIP: - [https://katacoda.com/dvc/](https://katacoda.com/dvc/) - [https://github.com/dashohoxha/katacoda-dvc-scenarios](https://github.com/dashohoxha/katacoda-dvc-scenarios) If you clone this repo to [GitHub - iterative/katacoda-scenarios: Interactive Katacoda Scenarios](https://github.com/iterative/katacoda-scenarios) (or [https://github.com/iterative/katacoda-tutorials](https://github.com/iterative/katacoda-tutorials) or something like this), and give me access to it, I can continue working there. Please don’t review it yet until I am done, because I may change and restructure it several times, until I think it is in a good shape. Please let me finish the Katacoda tutorials first, because this would also help me to get a more intimate knowledge of the details of DVC. Besides this, at the end of November I will have to submit my work to GSoD, and it seems better to submit something that is clearly my work, rather than a bunch of commits that are intermixed with the work of other people. I think that by the end of this month the Katacoda scenarios will be done, and next month I can start with the User Guide. However it seems that there are several people involved with the docs, and it is not so clear to me what are the responsibilities of each one and what are my responsibilities. I am afraid that we may step onto the toes of each-other if we work on the same files at the same time. > [@shcheklein](#): > > Re the top level sections. For each of them, I would start by creating a second level section in the User Guide first. Then we will decide which of them it makes sense to move to the top level. I agree on this. > [@shcheklein](#): > > Please, use Github and split the plan into some manageable issues/tickets. It’s very hard to discuss and give feedback on 6 large items at once. It’s not good to have two places for this kind of discussions. I will do it. Right now I am working on this one: [build interactive lessons with katacoda · Issue #546 · iterative/dvc.org · GitHub](https://github.com/iterative/dvc.org/issues/546) ---
**Author:** ![shcheklein](https://yyz1.discourse-cdn.com/flex035/user_avatar/discuss.dvc.org/shcheklein/32/173_2.png) [@shcheklein](https://discuss.dvc.org/u/shcheklein)\ **Post date:** [September 11, 2019, 4:06pm UTC](https://discuss.dvc.org/t/restructuring-docs/201/4 "2019-09-11T16:06:55Z")
> If you clone this repo to [GitHub - iterative/katacoda-scenarios: Interactive Katacoda Scenarios](https://github.com/iterative/katacoda-scenarios) Done! > Please let me finish the Katacoda tutorials first, because this would also help me to get a more intimate knowledge of the details of DVC Sure! Np. > [@dashohoxha](#): > > However it seems that there are several people involved with the docs, and it is not so clear to me what are the responsibilities of each one and what are my responsibilities. I am afraid that we may step onto the toes of each-other if we work on the same files at the same time. I think this is the case with any more or less popular/large project. At the end, it’s my job to make sure that work is split sanely. Also, it’s absolutely normal to work on a single file in certain cases - that’s what merge is for after all. > Besides this, at the end of November I will have to submit my work to GSoD, and it seems better to submit something that is clearly my work, rather than a bunch of commits that are intermixed with the work of other people. Any open-source by definition is a collaborative work where people work on top of previous stuff. So, I would not afraid to submit something that also has someone’s else name on it. Usually, it’s not a problem to see the value of individual contributions in this “mix”. ---
**Author:** ![dashohoxha](https://yyz1.discourse-cdn.com/flex035/user_avatar/discuss.dvc.org/dashohoxha/32/45_2.png) [@dashohoxha](https://discuss.dvc.org/u/dashohoxha)\ **Post date:** [September 11, 2019, 4:34pm UTC](https://discuss.dvc.org/t/restructuring-docs/201/5 "2019-09-11T16:34:21Z")
> [@shcheklein](#): > > > If you clone this repo to [GitHub - iterative/katacoda-scenarios: Interactive Katacoda Scenarios](https://github.com/iterative/katacoda-scenarios) > > Done! I also need to fix a webhook on the settings. Or I can show you how to do it. > [@shcheklein](#): > > Any open-source by definition is a collaborative work where people work on top of previous stuff. So, I would not afraid to submit something that also has someone’s else name on it. Usually, it’s not a problem to see the value of individual contributions in this “mix”. That’s right. I don’t think that GSoD can look at the details of the work of each person, maybe they just want to make sure that people are not abusing with the stipend and with the program. But as long as the mentors say that they have worked properly, everything should be OK. ---
**Author:** ![shcheklein](https://yyz1.discourse-cdn.com/flex035/user_avatar/discuss.dvc.org/shcheklein/32/173_2.png) [@shcheklein](https://discuss.dvc.org/u/shcheklein)\ **Post date:** [September 11, 2019, 5:15pm UTC](https://discuss.dvc.org/t/restructuring-docs/201/6 "2019-09-11T17:15:33Z")
> [@dashohoxha](#): > > I also need to fix a webhook on the settings. Or I can show you how to do it. I’ve provided you admin rights for this repo! Feel free to configure it properly.