Page MenuHomePhabricator

Rewrote airline demo readme
ClosedPublic

Authored by natekupp on Thu, Aug 1, 11:46 PM.

Details

Reviewers
max
Group Reviewers
Restricted Project
Commits
R1:f7cb9b801b45: Rewrote airline demo readme
Test Plan

docs only

Diff Detail

Repository
R1 dagster
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

natekupp created this revision.Thu, Aug 1, 11:46 PM
natekupp added a reviewer: Restricted Project.Thu, Aug 1, 11:50 PM

I'm worried by the amount of code in the readme - it can all go stale without noticing pretty easily. Not sure what alternative would be better.

examples/dagster_examples/airline_demo/README.md
75

whats this "!"?

157–160

"in practice" x2 - change up wording

423–424

on the papermill

'on papermill' ?

natekupp updated this revision to Diff 3379.Fri, Aug 2, 7:46 PM
natekupp marked 3 inline comments as done.

comments and wrapping

yeah agree re: amount of code - but arguably true for the exposition, YAML, UI screenshots, etc. also.

Maybe best bet would be to reduce the surface area of this README? it covers a _ton_ of ground for one document...

examples/dagster_examples/airline_demo/README.md
75

must've been some non-printing unicode character, it appears as a space in my editor - seems to be fixable

157–160

fixed

423–424

sg!

spitting out ideas:

  • just cite where the code is instead of inlining it "you can see this in fn_name in file.py"
  • move the content in to comment blocks - maybe tag them and then refer to those tags in this readme
natekupp updated this revision to Diff 3434.Tue, Aug 6, 4:38 PM

remove code blocks and replace w/ references

max added a subscriber: max.Tue, Aug 6, 7:08 PM

I'd prefer to move this to docs/.rst and build the code in through the Sphinx build process -- then link to the docs from a very short README,md in the demo directory.

natekupp updated this revision to Diff 3474.Tue, Aug 6, 10:43 PM

move to ReST

max accepted this revision.Wed, Aug 7, 6:25 PM
This revision is now accepted and ready to land.Wed, Aug 7, 6:25 PM
This revision was automatically updated to reflect the committed changes.