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.

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

Updating/Publishing the docs/ directory #774

Closed
ryan-williams opened this Issue Aug 14, 2015 · 4 comments

Comments

Projects
4 participants
@ryan-williams
Member

ryan-williams commented Aug 14, 2015

I only realized that the docs/ directory exists recently, when refactoring README.md (#763, #764).

@fnothaft implied on #764 that the docs there get distributed via released artifacts, but I don't see any in adam-distribution_2.10-0.17.0-bin.tar.gz.

It seems like there was a lot of somewhat-duplicated markdown living there, vs. what was in README; now the README is very different.

Are builds of docs/ available on the internet anywhere? How should we keep them updated / consistent with README.md? Is it up to anyone making changes to update the docs in both places?

Should we move towards setting up e.g. readthedocs.org builds of the docs for each version? Should the README point at those? I generally like that approach, though some way to also publish docs for random non-release SHAs/nightly-snapshots or something would also be good and has been lacking in other projects who've done something like this, e.g. Spark.

@massie

This comment has been minimized.

Show comment
Hide comment
@massie

massie Aug 14, 2015

Member

The docs are published with the releases. I had hoped that by using simple markdown, the barrier to updating them would be low. Unfortunately, we haven't been updating them once created, e.g. git log -- docs.

I'm open to any suggestions about how to do documentation better. I haven't used readthedocs.org so I can't comment from experience. I hope what we choose needs to create standalone docs (e.g. PDF, html, etc) and not be dependent on services.

Member

massie commented Aug 14, 2015

The docs are published with the releases. I had hoped that by using simple markdown, the barrier to updating them would be low. Unfortunately, we haven't been updating them once created, e.g. git log -- docs.

I'm open to any suggestions about how to do documentation better. I haven't used readthedocs.org so I can't comment from experience. I hope what we choose needs to create standalone docs (e.g. PDF, html, etc) and not be dependent on services.

@ryan-williams

This comment has been minimized.

Show comment
Hide comment
@ryan-williams

ryan-williams Aug 14, 2015

Member

Ah, thx @massie, I see the PDF and HTML downloads on the releases/ page now. Thanks for the additional context as well; I don't have any great ideas at the moment but I'll leave this here until inspiration strikes someone.

Member

ryan-williams commented Aug 14, 2015

Ah, thx @massie, I see the PDF and HTML downloads on the releases/ page now. Thanks for the additional context as well; I don't have any great ideas at the moment but I'll leave this here until inspiration strikes someone.

@fnothaft fnothaft added this to the 1.0.0 milestone Mar 3, 2017

@fnothaft

This comment has been minimized.

Show comment
Hide comment
@fnothaft

fnothaft Mar 3, 2017

Member

We should push this to our github pages.

Member

fnothaft commented Mar 3, 2017

We should push this to our github pages.

@heuermh

This comment has been minimized.

Show comment
Hide comment
@heuermh

heuermh Apr 11, 2017

Member

Fixed by #1461.

Member

heuermh commented Apr 11, 2017

Fixed by #1461.

@heuermh heuermh closed this Apr 11, 2017

@heuermh heuermh modified the milestones: 1.0.0, 0.23.0 Dec 7, 2017

@heuermh heuermh added this to Completed in Release 0.23.0 Jan 4, 2018

@heuermh heuermh moved this from Triage to Completed in Release 1.0.0 Jan 4, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment