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

Add a suggestions section #4

Merged
merged 1 commit into from
Aug 22, 2017
Merged

Add a suggestions section #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
262 changes: 205 additions & 57 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,7 +230,8 @@ <h3 class="title is-4 has-text-centered has-text-light">
Input (editable)
</h3>
<textarea>
# Foobar
# Foobar ![CI status](https://img.shields.io/badge/build-passing-brightgreen.svg)

Foobar is a Python library for doing awesome things with strings.

## Installation
Expand Down Expand Up @@ -260,6 +261,8 @@ <h3 class="title is-4 has-text-centered has-text-light">
Pull requests are welcome. For major changes, please open an issue first
to discuss what you would like to change.

Please make sure to update tests as appropriate.

## License
[MIT](https://choosealicense.com/licenses/mit/)</textarea>
</div>
Expand All @@ -272,6 +275,207 @@ <h3 class="title is-4 has-text-centered has-text-light">
</div>
</section>

<section class="section">
<div class="container">
<h2 class="title is-3 has-text-centered">
Suggestions for a good README
</h2>

<p>
Every project is different, so consider which of these
suggestions apply to yours. Also keep in mind that while a
README can be too long and detailed, too long is better
than too short. If you think your README is too long, consider
utilizing
<a href="#more-documentation">another form of documentation</a>
rather than cutting out information.
</p>

<br>

<h3 class="title is-4">
Name and description
</h3>
<p>
Make it immediately obvious what your project does at a
high level.
</p>

<br>

<h3 class="title is-4">
Badges
</h3>
<p>
On some READMEs, you may see small images that convey
metadata, such as whether or not all the tests
are passing for the project. You can use
<a href="http://shields.io/">Shields</a>
to add some to your README. Many services also have
instructions for adding a badge.
</p>

<br>

<h3 class="title is-4">
Features
</h3>
<p>
Let people know what your project can do specifically. If
there is an alternative to your project, this is a good
place to list differentiating factors.
</p>

<br>

<h3 class="title is-4">
Requirements
</h3>
<p>
If your project only works in a certain context, it's important
to be upfront about its requirements. Otherwise, someone may
try to use your project, only to discover that it requires
a certain version of a language or a particular operating
system.
</p>

<br>

<h3 class="title is-4">
Installation
</h3>
<p>
Within a particular ecosystem, there may be a standard way of
installing projects. However, consider the possibility
that whoever is reading your README is a novice and needs
more guidance. Listing specific steps helps remove ambiguity
and gets people to using your project as quickly as possible.
</p>

<br>

<h3 class="title is-4">
Usage
</h3>
<p>
Use examples liberally, and show the expected output.
</p>

<br>

<h3 class="title is-4">
Support
</h3>
<p>
Tell people where they can go to for help. It could be any
combination of an issue tracker, a chat room, an email
address, etc.
</p>

<br>

<h3 class="title is-4">
Development
</h3>
<p>
For people who want to make changes to your project,
it's helpful to have some documentation on how to get started.
Perhaps there is a script that they should run or some
environment variables that need to be set. Make these steps
explicit. These instructions could also be useful to your
future self.
</p>

<br>

<h3 class="title is-4">
Contributing
</h3>
<p>
If you are open to contributions from others, let them know
what your requirements are for accepting contributions.
</p>

<br>

<h3 class="title is-4">
Authors and acknowledgment
</h3>
<p>
Show your appreciation to those who have contributed to the
project.
</p>

<br>

<h3 class="title is-4">
License
</h3>
<p>
For open source projects, say how it is
<a href="#license-1">licensed</a>.
</p>
</div>
</section>

<section id="faq" class="section">
<h2 class="title has-text-centered has-text-light">
FAQ
</h2>

<article class="message is-warning">
<h3 class="message-header">
Is there a standard README format?
</h3>
<div class="message-body">
Nope. It's really up to developers what info they want to
include in the README.
</div>
</article>

<article class="message is-warning">
<h3 class="message-header">
What should the README file be named?
</h3>
<div class="message-body">
<code>README.md</code> (or a different file extension if you
choose to use a non-Markdown file format). It is
traditionally capital case so that it is more prominent
and so that it shows up towards the beginning of <code>ls</code>
output.
</div>
</article>

<article class="message is-warning">
<h3 class="message-header">
What if I disagree with something, want to make a change, or
have any other feedback?
</h3>
<div class="message-body">
Please don't hesitate to <a href="https://github.com/dguo/make-a-readme/issues">open an issue</a>
or <a href="https://github.com/dguo/make-a-readme/pulls">pull request</a>.
You can also send me a message on <a href="https://twitter.com/dannyguo">Twitter</a>.
</div>
</article>

<article class="message is-warning">
<h3 class="message-header">
Mind reading?
</h3>
<div class="message-body">
<a href="https://www.usatoday.com/story/tech/2014/04/22/mind-reading-brain-scans/7747831/">Scientists</a>
and companies like
<a href="https://www.theverge.com/2017/4/20/15375176/facebook-regina-dugan-interview-building-8-mind-reading-f8-2017">Facebook</a>
and <a href="https://www.neuralink.com/">Neuralink</a> (presumably) are working on it.
Perhaps in the future, you'll be able to attach a copy of your
thoughts and/or consciousness to your projects. In the meantime,
please make READMEs. :)
</div>
</article>
</section>



<section class="section">
<div class="container">
<h2 class="title has-text-centered">
Expand Down Expand Up @@ -345,62 +549,6 @@ <h3 class="title is-4">
</div>
</section>

<section id="faq" class="section">
<h2 class="title has-text-centered has-text-light">
FAQ
</h2>

<article class="message is-warning">
<h3 class="message-header">
Is there a standard README format?
</h3>
<div class="message-body">
Nope. It's really up to developers what info they want to
include in the README.
</div>
</article>

<article class="message is-warning">
<h3 class="message-header">
What should the README file be named?
</h3>
<div class="message-body">
<code>README.md</code> (or a different file extension if you
choose to use a non-Markdown file format). It is
traditionally capital case so that it is more prominent
and so that it shows up towards the beginning of <code>ls</code>
output.
</div>
</article>

<article class="message is-warning">
<h3 class="message-header">
What if I disagree with something, want to make a change, or
have any other feedback?
</h3>
<div class="message-body">
Please don't hesitate to <a href="https://github.com/dguo/make-a-readme/issues">open an issue</a>
or <a href="https://github.com/dguo/make-a-readme/pulls">pull request</a>,
or send me a message on <a href="https://twitter.com/dannyguo">Twitter</a>.
</div>
</article>

<article class="message is-warning">
<h3 class="message-header">
Mind reading?
</h3>
<div class="message-body">
<a href="https://www.usatoday.com/story/tech/2014/04/22/mind-reading-brain-scans/7747831/">Scientists</a>
and companies like
<a href="https://www.theverge.com/2017/4/20/15375176/facebook-regina-dugan-interview-building-8-mind-reading-f8-2017">Facebook</a>
and <a href="https://www.neuralink.com/">Neuralink</a> (presumably) are working on it.
Perhaps in the future, you'll be able to attach a copy of your
thoughts and/or consciousness to your projects. In the meantime,
please make READMEs. :)
</div>
</article>
</section>

<footer class="footer content has-text-centered"
style="margin-bottom: 0px; padding-top: 2em; padding-bottom: 2em;">
<p>
Expand Down