READMEhowto/index.html at main · NotesFromBritt/READMEhowto · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta
      name="description"
      content="This technical document teaches you how and why to use a ReadMe file."
    />

    <link rel="stylesheet" href="styles.css" />
    <title>README How To</title>
  </head>
  <body>
    <nav id="navbar">
      <header><h1>README File Basics</h1></header>
      <ul>
        <li>
          <a
            class="nav-link"
            href="#Introduction"
            title="Jump to Document Introduction"
            >Introduction</a
          >
        </li>
        <li>
          <a
            class="nav-link"
            href="#What_is_a_README_file"
            title="Jump to What is a readme?"
            >What is a README file</a
          >
        </li>
        <li>
          <a
            class="nav-link"
            href="#Why_to_have_a_README"
            title="Jump to Why to have a readme?"
            >Why to have a README</a
          >
        </li>
        <li>
          <a
            class="nav-link"
            href="#What_to_include"
            title="Jump to What to included?"
            >What to include</a
          >
        </li>
        <li>
          <a
            class="nav-link"
            href="#How_to_format"
            title="Jump to How to format?"
            >How to format</a
          >
        </li>
        <li>
          <a class="nav-link" href="#Extra_Credit" title="Extra Credit!"
            >Extra Credit</a
          >
        </li>
      </ul>
    </nav>
    <main id="main-doc">
      <section class="main-section" id="Introduction">
        <header>Introduction</header>
        <article>
          <p>
            In this document you will learn what a README file is, why you
            should use them and how to create one that is clear and easy to
            understand.
          </p>
          <p>
            The goal is for you to have a general understanding and to preform
            continued research in order to gain the insight you need.
          </p>
        </article>
      </section>

      <section class="main-section" id="What_is_a_README_file">
        <header>What is a README file?</header>
        <article>
          <p>
            A README file is a text file that contains information for all other
            files within a directory. The README file serves as a type of manual
            and a way for visitors to learn the What, Why and How of the
            project.
          </p>
          <p>Many times this is the first file a user will view.</p>
          <p>
            The file name is usually written in uppercase letters, for example:
          </p>
          <code>README.TXT, READ.ME, README.md</code>
        </article>
      </section>

      <section class="main-section" id="Why_to_have_a_README">
        <header>Why to have a README</header>
        <article>
          <p>
            Think of your README as a kind of home-base for your directory. This
            is the place for you to include detailed documentation that will
            allow your project to be easily navigated. Why? The easier your
            project is to navigate the more engagement you will receive.
          </p>
          <br />
          <p><b>The README file will allow visitors to:</b></p>
          <ul>
            <li>Engage with your project.</li>
            <li>Navigate your code easily.</li>
            <li>Find answer to common questions.</li>
            <li>Determine what the project is about.</li>
            <li>Learn how the project is used.</li>
            <li>Discover how your project was made.</li>
          </ul>
          <p>
            It is encouraged that ever project include a detailed README file.
            Make a routine of creating a README file with every project you
            create.
          </p>

          <code
            >The first thing you should create for every project is your README
            file.</code
          >
        </article>
      </section>

      <section class="main-section" id="What_to_include">
        <header>What to include?</header>
        <article>
          <p>
            Every README file should include important documentation. This can
            include anything the creator chooses but the most important items
            are a Title, Description and How To.
          </p>
          <br />
          <p><b>The following are recommended:</b></p>
          <ul>
            <li>Title</li>
            <li>Short Description or Summary</li>
            <li>Table of Contents (for large projects)</li>
            <li>How to Install or Run Project</li>
            <li>Roadmap or Project Status</li>
            <li>How to Contribute</li>
            <li>Demo Screenshots</li>
            <li>Credits</li>
            <li>Licenses</li>
            <li>Badges</li>
          </ul>
          <code
            >To make sure your visitor can navigate your project have your
            README organized and easy to understand.</code
          >
        </article>
      </section>

      <section class="main-section" id="How_to_format">
        <header>How to format</header>
        <article>
          <p>
            Typically a README is created in text file format with markdown.
            This will allow creativity in a clean minimalist format.
          </p>
          <p>
            While you can freehand the creation of your README there are
            applications out there to help maximize your time and organization.
          </p>
          <p><i>For example: https://www.mkdocs.org/ is a great site.</i></p>
          <code
            >Your README can be simple and minimalistic! Just make sure to
            include the important details.
          </code>
        </article>
      </section>

      <section class="main-section" id="Extra_Credit">
        <header>Extra Credit</header>
        <article>
          <ul>
            <li>
              Read this great articles about creating a README on
              <a
                href="https://github.com/matiassingers/awesome-readme"
                target="_blank"
                >GitHub</a
              >.
            </li>
          </ul>
          <code
            >Open-source code by
            <a
              href="https://github.com/Tinymrsb"
              target="_blank"
              title="Brittany Shaw's Github"
              >Brittany Shaw</a
            >. Share your this article with your friends!</code
          >
        </article>
      </section>
    </main>
  </body>
</html>