-
Notifications
You must be signed in to change notification settings - Fork 484
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
Conversation
There was a problem hiding this 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?
This way they can still serve as good internal documentation, without cluttering the publicly visible README
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 |
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.