dvc.org
dvc.org copied to clipboard
iterative
READMEs vs Docs
From https://github.com/iterative/cml/pull/492#pullrequestreview-650736268
We need to decide on a clear scope of README files (and, ahem, cough, cough docs). Right now, https://dvc.org/doc/cml is just a mirror of https://github.com/iterative/cml meaning a lot of duplication - but there may be more things which need addressing too. Related: #2433.
UPDATE: See recent summary in https://github.com/iterative/dvc.org/issues/2443#issuecomment-1144410100.
My personal preference is:
- features: https://PRODUCT.com/features (heavy on graphics, low on text. High level intro to solutions)
- maybe just https://PRODUCT.com if there's no better content for the site root
- docs: https://PRODUCT.com/doc
- Use Cases (features elaborated. High level intro to problems)
- Getting Started (beginner tutorials)
- User Guide (advanced tutorials/how-tos)
- Command/API Reference (man pages)
- README (targeted at "power users"/devs)
- status badges (related: our own badge #234)
- installation methods
- super short summary of (in order): Use Cases + Features (list/diagram), Getting Started (briefest possible tutorial), link to User Guide, link to Command/API Reference
- links to related technologies
- link to Contributing
- link to Mailing List & forums
- licen[c/s]e & citation
I think most agree that https://dvc.org/doc/cml should be a one page blurb containing links to cml.dev
- [x] DVC readme #2433
- [x] DVC badges #234
- [ ] CML (readme, https://github.com/iterative/cml-website/issues/55, wiki) https://github.com/iterative/cml/issues/514
- [x] TPI?
- [x] DVCLive https://github.com/iterative/dvclive/issues/45
- ~~DVC.org website #144~~
- [ ] MLEM https://github.com/iterative/mlem/pull/220
- [ ] GTO https://github.com/iterative/gto/pull/149
- [ ] VSCode Extension https://github.com/iterative/vscode-dvc/pull/1816
- LDB ...
- Studio?
Great proposal! I have two questions:
* features: https://PRODUCT.com/features (heavy on graphics, low on text. High level intro to solutions)
What is the goal of the features page? It's been previously discussed that the existing dvc features page may not be that useful. Maybe we can take a look at the popularity of this page and decide whether the current format is useful.
* links to related technologies
Does this mean something like https://github.com/iterative/dvc#comparison-to-related-technologies, where there is a link to each related technology and a short explanation of how it relates? Does it mean a link to a docs page that explains how the product relates to other technologies?
I lean towards leaving this out of the README and having a separate doc comparing technologies (if needed) to keep the readme shorter and to allow for a more in-depth comparison elsewhere. Some examples:
- https://spacy.io/usage/facts-figures#comparison
- https://valohai.com/mlops-platforms-compared/
What is the goal of the features page?
Anything which doesn't exclusively target devs (i.e. purely marketing material targeting managers, and possibly also devs)
Does this mean something like iterative/dvc#comparison-to-related-technologies
yes
a link to a docs page that explains how the product relates to other technologies?
That sounds like something for the bottom of the "features" page. Wouldn't necessarily mention it in the README.
We can probably keep further discussion of the features and related technologies in separate tickets since there seems to be agreement that they don't belong in the readme, or at least should be as minimal as possible there.
Great topic!
features: https://PRODUCT.com/features Use Cases (features elaborated. High level intro to problems) Use Cases + Features (list/diagram) Anything which (that 😋) doesn't exclusively target devs
We have been considering merging that with the Use Cases (currently inside docs but unclear whether they belong there), and instead have visual-oriented "features" right in the home page (which we already try to do in dvc.org/, see below).
Also the Get Started has an overview of DVC features...
But maybe we should further extract this part of the discussion? Rel. #144
docs: https://PRODUCT.com/doc
Minor: I would personally prefer /docs but lost that battle some time ago ⚔️
User Guide (advanced tutorials)
Another minor note: guides aren't really tutorials (not meant to be, at least), they're more of an explanation-type doc (ref) and sometimes have even deeper details than the references.
Agree about README contents in general 👍 (links may vary as needed)
https://dvc.org/doc/cml should be a one page blurb containing links to cml.dev
Wouldn't your proposal imply creating cml.dev/doc to put guides and refs in?
We have been considering merging that with the Use Cases (currently inside docs but unclear whether they belong there), and instead have visual-oriented "features" right in the home page (which we already try to do in dvc.org/, see below).
Sure, I don't have strong opinions on /features versus /. If / has no real content then /features may as well be moved to it.
Also the Get Started has an overview of DVC features...
Yes, but only minimally as an augmented table of contents for its main purpose (i.e. getting started ToC rather than feature overview).
But maybe we should further extract this part of the discussion? Rel. #144
The main point of this issue is about what to put in READMEs. I only mention websites as tangential to prompt ideas. #144 is so longstanding I'm surprised that the tangential discussion here seems to be largely in agreement solving it :)
Minor: I would personally prefer /docs but lost that battle some time ago :crossed_swords:
I don't mind. Slight preference for shorter URLs.
User Guide (advanced tutorials) [...] aren't really [...] meant to be [tutorials ...] they're more of an explanation-type doc (ref) and sometimes have even deeper details than the references.
idk what the original plan was, but they look like what I call "advanced tutorials" to me at the moment. Based on the divio ref link, this would be currently labelled "How-Tos" rather than "Explanations." Also in terms of importance I'd say "How-To" is much more important to have than "Explanation," which may be why the original plan wasn't adhered to.
Wouldn't your proposal imply creating cml.dev/doc[s] to put guides and refs in?
Yup. Working on it.
this would be currently labelled "How-Tos" rather than "Explanations."
We have a how-to section https://dvc.org/doc/user-guide/how-to/stop-tracking-data BTW
idk what the original plan was
There was no original plan, we're improving as we go. The current intention is that Guides contain explanations
in terms of importance I'd say "How-To" is much more important
Why? Interested in your fresh perspective
in terms of importance I'd say "How-To" is much more important
Why? Interested in your fresh perspective
People are much more likely to first ask "How can I solve my problem?" (How-To) rather than "Thanks for solving my problem - how exactly did your solution work, btw?/I'm having an existential crisis. Why does my problem exist?/Where do we come from?/What is the meaning of life, the universe and everything?" (Explanation).
I'd prefer to know the meaning of life TBH. Otherwise yes, How-tos should get more quick traffic for sure: basically a support FAQ I guess?
BTW should we merge this issue with #2433?
I'd prefer to know the meaning of life TBH. Otherwise yes, How-tos should get more quick traffic for sure: basically a support FAQ I guess?
yeah, I like explanations too but I don't think the rest of the world has the same priorities.
BTW should we merge this issue with #2433?
I think #2433 is a DVC-specific part of this (more general cross-project) issue so wouldn't merge it. I'd add an epic label here and cross-ref other issues/PRs (incl. #2433).
Good idea, either epic this, or extract the README-specific stuff to #2433 and make them clearly different? Up to you
Also related: https://github.com/iterative/dvclive/issues/45 cc @pared
Henlo
We recently discussed this (and closed #2433) so I wanted to restart the conversation so we have a plan of action with the different core teams that maintain the product repos, starting with dvc cc @dberenbaum
@casperdcl's proposal is to follow the pattern in https://github.com/iterative/terraform-provider-iterative#readme:
- Banner/badges
- Short intro with main features
- Figure? If needed
- Sell the benefits
- Compressed yet comprehensive Usage
- How it Works - basic explanation, preferably a diagram
- Other sections
My feedback on that README is that a) the features and benefits sections overlap quite a bit I think there could be a single intro section with all that to get to Usage faster b) How it Works may not be necessary IF there's a docs website for the tool where we can link to instead
Also I'd propose adding a ToC near the top if we're going with a long format.
Thoughts?
@casperdcl's proposal is to follow the pattern in https://github.com/iterative/terraform-provider-iterative#readme
I would say "my" proposal (with lots of feedback & iterations with @dmpetrov) is:
AS COMPLETE_AND_CONCISE AS POSSIBLE, assume readers lack patience
no-scroll:
- Banner/badges
- Features
- Diagram
scroll down:
- Unique Selling Points (i.e. why it's better than alternatives)
- Usage (in-place complete-yet-minimal-working-example quickstart)
- requirements & installation
- example/tutorial
- links to more Use cases/tutorials
- Architecture/in-depth explanation/diagrams (target advanced devs & contributors)
- Future plans/Roadmap
- Help & Debugging (
--verbose/export DEBUG=1/GH issue links/docs links) - Contributing (requirements & installation for contributors)
- Copyright/licence
features and benefits sections overlap quite a bit I think there could be a single intro section with all that to get to Usage faster
disagree - the "Features" completely describe the solution, and capture attention of appropriate users (acquisition). The "USPs" describe why no other solution is better (retention).
How it Works may not be necessary IF there's a docs website
there's a docs website for everything (incl for TPI) but the point is to put a minimal reference in the readme. Links are fine but there should also be a concise summary in the readme for local devs who hate websites (there are a lot).
Also I'd propose adding a ToC near the top
GH auto-generates ToC - we don't need to add this explicitly.
- Features
I think it should be something like workflows rather than features. We should be focusing on how users interact with the product.
that... would be "Use cases" instead of "Features?"
idk if it's possible to cram all the use cases into the top of the readme. Would be great if possible.
Was thinking use cases could be part of Examples further down...
If we consider Features as on this page https://dvc.org/features then I would prefer to have a short list of Use cases instead, features are not very meaningful if I don't understand why would I want to use the tool.
And to clarify, even an entry paragraph can answer "why use it" question.
that... would be "Use cases" instead of "Features?"
I was thinking somewhere in between. Since we are building modular tools, it should be possible to have a paragraph or a few bullets to explain the basic expected workflow.
Related:
- https://github.com/iterative/dvc/pull/7723
- https://github.com/iterative/terraform-provider-iterative/issues/558.
idk if it's possible to cram all the use cases into the top of the readme. Would be great if possible.
Was thinking use cases could be part of Examples further down...
Yeah, makes sense. IMO the intro should be a lower level explanation of how to interact with the tool, and use cases might still be relevant to describe different high-level scenarios. For TPI, I would expect the intro to be about how to train/run ML jobs in the cloud, while lower down would be use cases like remote Jupyter notebooks.
To summarize
- Header, banners
No-scroll
- Main value proposition This answers "why should I care".
- Include what the tool is (a CLI, a library, a GUI)
- Mention use cases or things you can do. Either as an actual list or a (part of) a clear paragraph Further hooks people for a specific reason.
- Diagrams I think are optional as needed? One could go here.
Scroll
Everything else is more flexible, up to each product. One example:
- Compressed "quick start" / basic workflow (happy path) including installation + maybe config info.
- Comprehensive list(s) of features/commands, linked to full doc guides or refs.
- Complete usage reference/guide if needed It could be a separate md file linked from the README too.
- More conceptual "How it works" stuff + diagrams (ideally only if there's no docs site)
- Other info. (support, debugging/contrib, license or copyright, telemetry, etc.)
Other notes like current state or future roadmap can be added as needed, we don't need to plan for it in this template.
Are there org-level issues/discussions? This goes beyond DVC at this point.
For now I updated the task list at the bottom of the OP desc ☑️ ☑️ ☑️
No-scroll
- Header, banners
- Main value proposition
- what the tool is (a CLI, a library, a GUI)
- use cases
seems impossible sans diagrams. Spacing would have to be:
- banner images + title + badges take >5 lines
- paragraph
- sentence part of 1 (don't see why it's separate?)
- best shown in multiple flowcharts
I just don't think we can expect mandatory diagrams in every README.
don't see why it's separate?
It's a separate item in my list but can be in the same paragraph of course. I just wanted to emphasize not to forget this.
Interesting guidelines: https://github.com/ddbeck/readme-checklist (via @omesser thanks)
about READMEs, I like the minimal one from deno, i.e.:
- USP list
- cross-platform installation
- get started snippet
- contributing link
I think a lot of things here have been done. Closing this. I put a link in Notion to this dicussion.