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.

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

Moved improved ‘Inventory’ section of ‘README.md’ into separate ‘Inventory.md’ file #112

Merged
merged 13 commits into from
Aug 29, 2019

Conversation

regexident
Copy link
Collaborator

@regexident regexident commented Aug 19, 2019

The one inventory reference to rule them all! 🤘🏻

Disclaimer: This inventory assumes a post-completion state of https://github.com/mattt/Surge/issues/106.

Notable mention: Sprinkled all over the file you find <!-- FIXME: … --> comments addressing API inconsistencies that revealed themselves during the document's assembly.

Copy link
Collaborator

@mattt mattt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👏

This is wonderful. It's really nice to have a summary of all of the available functions and operators all together like this.

The only question I have is, why move this out of README? As much as I appreciate organizing information, there's (unfortunately) a very high cost to splitting up information like this. Everyone sees the README, but almost nobody will find a Github Wiki page or a Markdown file in a docs directory — even when it's linked from the README. Folks seem not to mind at all scrolling through a long README, and the use of <details> and a TOC alleviate much of the cost.

What do you think about keeping all of this great information in the README?

@regexident
Copy link
Collaborator Author

Those are some more than valid points! I'll move it back into README.

The reason I extracted it was that I feared it would add too much bloat to the README (as the use of <details> only later occurred to me while working on the file) and hide potentially important information from the bottom of the README (which of course can be avoided easily by simply pushing the inventory to the very bottom of the document).

@regexident regexident merged commit 03b3a35 into Jounce:master Aug 29, 2019
@regexident regexident deleted the inventory branch August 29, 2019 23:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants