Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

READMEs vs Docs #2443

Closed
4 of 8 tasks
casperdcl opened this issue May 4, 2021 · 26 comments
Closed
4 of 8 tasks

READMEs vs Docs #2443

casperdcl opened this issue May 4, 2021 · 26 comments
Labels
A: docs Area: user documentation (gatsby-theme-iterative) ✨ epic Placeholder ticket for multi-sprint direction, use story, improvement type: discussion Requires active participation to reach a conclusion.

Comments

@casperdcl
Copy link
Contributor

casperdcl commented May 4, 2021 •
edited by jorgeorpinel

From iterative/cml#492 (review)

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 #2443 (comment).

My personal preference is:

  • features: https://PRODUCT.com/features (heavy on graphics, low on text. High level intro to solutions)
  • 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 DVC 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
@casperdcl casperdcl mentioned this issue May 4, 2021
Merged
@shcheklein
Copy link
Member

LGTM! :)

@dberenbaum
Copy link
Contributor

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:

@casperdcl
Copy link
Contributor Author

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.

@dberenbaum
Copy link
Contributor

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.

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented May 5, 2021 •
edited

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).

image

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?

@casperdcl
Copy link
Contributor Author

casperdcl commented May 5, 2021 •
edited

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 ⚔️

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.

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented May 6, 2021 •
edited

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

@casperdcl
Copy link
Contributor Author

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).

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented May 6, 2021 •
edited

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?

@jorgeorpinel jorgeorpinel added the p1-important Active priorities to deal within next sprints label May 6, 2021
@jorgeorpinel jorgeorpinel mentioned this issue May 6, 2021
Closed
@casperdcl
Copy link
Contributor Author

casperdcl commented May 6, 2021 •
edited

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).

@jorgeorpinel
Copy link
Contributor

Good idea, either epic this, or extract the README-specific stuff to #2433 and make them clearly different? Up to you

@jorgeorpinel
Copy link
Contributor

BTW (if this is an epic), is this related too? #234

@casperdcl casperdcl added the ✨ epic Placeholder ticket for multi-sprint direction, use story, improvement label May 6, 2021
@jorgeorpinel

This comment has been minimized.

Sign in to view
@tapadipti tapadipti mentioned this issue May 11, 2021
Merged
@casperdcl casperdcl mentioned this issue May 13, 2021
Closed
14 tasks
@casperdcl casperdcl changed the title READMEs vs docs READMEs vs doc(s) May 17, 2021
@casperdcl casperdcl mentioned this issue May 17, 2021
Closed
This was referenced Jun 10, 2021
Closed
Closed
This was referenced Jul 1, 2021
Merged
Closed
@jorgeorpinel jorgeorpinel added type: discussion Requires active participation to reach a conclusion. A: docs Area: user documentation (gatsby-theme-iterative) and removed p1-important Active priorities to deal within next sprints type: discussion Requires active participation to reach a conclusion. labels Jan 14, 2022
@jorgeorpinel jorgeorpinel changed the title READMEs vs doc(s) READMEs vs Docs Jan 14, 2022
@casperdcl casperdcl mentioned this issue Mar 23, 2022
Closed
17 tasks
@casperdcl casperdcl mentioned this issue Apr 19, 2022
Open
21 tasks
@jorgeorpinel jorgeorpinel added the p1-important Active priorities to deal within next sprints label Apr 27, 2022
@jorgeorpinel
Copy link
Contributor

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
Copy link
Contributor Author

casperdcl commented May 9, 2022 •
edited

@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.

image

@dberenbaum
Copy link
Contributor

  • Features

I think it should be something like workflows rather than features. We should be focusing on how users interact with the product.

@casperdcl
Copy link
Contributor Author

casperdcl commented May 9, 2022 •
edited

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...

@shcheklein
Copy link
Member

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.

@dberenbaum
Copy link
Contributor

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:

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.

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Jun 2, 2022 •
edited

To summarize

  1. Header, banners

No-scroll

  1. Main value proposition
    This answers "why should I care".
  2. Include what the tool is (a CLI, a library, a GUI)
  3. 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.

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Jun 2, 2022 •
edited

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 ☑️ ☑️ ☑️

@jorgeorpinel jorgeorpinel removed the p1-important Active priorities to deal within next sprints label Jun 2, 2022
jorgeorpinel added a commit to iterative/vscode-dvc that referenced this issue Jun 2, 2022
@jorgeorpinel
readme: reorg existing content per
304599d 
per iterative/dvc.org#2443
jorgeorpinel added a commit to iterative/vscode-dvc that referenced this issue Jun 2, 2022
@jorgeorpinel
readme: reorg existing content per
7a089a1 
per iterative/dvc.org#2443 (comment)
@casperdcl
Copy link
Contributor Author

casperdcl commented Jun 2, 2022 •
edited

No-scroll

  1. Header, banners
  2. Main value proposition
  3. what the tool is (a CLI, a library, a GUI)
  4. use cases

seems impossible sans diagrams. Spacing would have to be:

  1. banner images + title + badges take >5 lines
  2. paragraph
  3. sentence part of 1 (don't see why it's separate?)
  4. best shown in multiple flowcharts

@jorgeorpinel jorgeorpinel mentioned this issue Jun 2, 2022
Merged
@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Jun 2, 2022 •
edited

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.

@jorgeorpinel jorgeorpinel mentioned this issue Jun 8, 2022
Merged
2 tasks
This was referenced Jun 11, 2022
Merged
Merged
shcheklein pushed a commit to iterative/vscode-dvc that referenced this issue Jun 14, 2022
@jorgeorpinel @dberenbaum
@mattseddon @restyled-commits
README rewrite (+ CONTRIB updates) (#1816)
2f6b3cb 
* readme: make intro = value prop +
+ fancy note

* readme: spave between VS and Code
per #1816 (review)

* readme: reorg existing content per
per iterative/dvc.org#2443 (comment)

* readme: add features list

* readme: extend/fix/link other parts of the structure

* readme: fix DVC icon

* readme: value prop edited from
https://docs.google.com/document/d/10THN0WwvPaDOAnmWd37xMOSWftJrUSIPlA2m0iHGDNI/edit#
per #1816 (comment)

* Update README.md

Co-authored-by: Dave Berenbaum <dave.berenbaum@gmail.com>

* Update README.md

* readme: rewrap

* readme: add list of high-level features
from https://docs.google.com/document/d/10THN0WwvPaDOAnmWd37xMOSWftJrUSIPlA2m0iHGDNI/edit#

* readme: update features and add competitive advantages
based on https://docs.google.com/document/d/10THN0WwvPaDOAnmWd37xMOSWftJrUSIPlA2m0iHGDNI/edit#

* readme: mention that it's beta
per #1816 (comment)

* readme: small improvements to lists

* readme: better Quick start

* readme: populate Config section

* readme: move Useful commands before Config

* config: update settings descriptions (readme and package)

* contrib: copy edits

* readme: fix vs-code commands lnk

* contrib: kill link to wiki (outdated)

* readme: lint (BROKEN)

* Update README.md

Co-authored-by: mattseddon <37993418+mattseddon@users.noreply.github.com>

* Update README.md

Co-authored-by: mattseddon <37993418+mattseddon@users.noreply.github.com>

* fix linter-broken line

* contrib: simpler dev env steps

* readme: better intro wording
per #1816 (review)

* readme: plots view -> dashboard :/
per #1816 (comment)

* readme: support should go to Discord first
per #1816 (review)
and #1816 (review)

* readme: exp bookkeeping -> tracking
per #1816 (review)

* readme: clarify reproducibility feature
per #1816 (review)

* readme: more specific data mgmt use
per #1816 (review)

* readme: improve UI components list
per #1816 (review)

* readme: fix img hack
may not work until repo goes public

* add badges to README

* drop some badges

* preview banner

* update link to point to main

* preview gif

* readme: impro feats

* contrib: move note about DVC projects

* revert to changelog from main and add prettier rule

* Update README.md

Co-authored-by: mattseddon <37993418+mattseddon@users.noreply.github.com>

* readme: move animation after value prop paragraph

* Apply suggestions from code review

Co-authored-by: mattseddon <37993418+mattseddon@users.noreply.github.com>

* Update README.md

* Restyled by whitespace

* Restyled by prettier-markdown

* Update README.md

* contrib: valid md new line >:(

* readme: move images to extension/images and
and add screenshot of Get Started page

* readme: move images back to extension/docs/ foler
per #1816 (review)

* swap banner to png

* replace outdated walkthrough screenshot

* update style of inline dvc png so it does not look bonkers

* (fixup) use absolute links for the marketplace and in product

Co-authored-by: Dave Berenbaum <dave.berenbaum@gmail.com>
Co-authored-by: mattseddon <37993418+mattseddon@users.noreply.github.com>
Co-authored-by: Matt Seddon <mattseddon@hotmail.com>
Co-authored-by: Restyled.io <commits@restyled.io>
@jorgeorpinel jorgeorpinel mentioned this issue Jul 7, 2022
Open
@jorgeorpinel jorgeorpinel mentioned this issue Nov 18, 2022
Open
@jorgeorpinel
Copy link
Contributor

Interesting guidelines: https://github.com/ddbeck/readme-checklist (via @omesser thanks)

@casperdcl
Copy link
Contributor Author

about READMEs, I like the minimal one from deno, i.e.:

  • USP list
  • cross-platform installation
  • get started snippet
  • contributing link

@shcheklein
Copy link
Member

I think a lot of things here have been done. Closing this. I put a link in Notion to this dicussion.

@omesser omesser added the type: discussion Requires active participation to reach a conclusion. label Mar 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A: docs Area: user documentation (gatsby-theme-iterative) ✨ epic Placeholder ticket for multi-sprint direction, use story, improvement type: discussion Requires active participation to reach a conclusion.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@jorgeorpinel @dberenbaum @shcheklein @casperdcl @omesser