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
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
<!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">
<link rel="shortcut icon" href="../img/favicon.ico">
<title>Introduction - Vim</title>
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.12.0/css/all.css">
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.12.0/css/v4-shims.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/hack-font@3.3.0/build/web/hack.min.css">
<link href='//rsms.me/inter/inter.css' rel='stylesheet' type='text/css'>
<link href='//fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,700italic,400,300,600,700&subset=latin-ext,latin' rel='stylesheet' type='text/css'>
<link href="../css/bootstrap-custom.min.css" rel="stylesheet">
<link href="../css/base.min.css" rel="stylesheet">
<link href="../css/cinder.min.css" rel="stylesheet">
<link rel="stylesheet" href="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.18.0/build/styles/github.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://cdn.jsdelivr.net/npm/html5shiv@3.7.3/dist/html5shiv.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/respond.js@1.4.2/dest/respond.min.js"></script>
<![endif]-->
</head>
<body>
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<!-- Main title -->
<a class="navbar-brand" href="..">Vim</a>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li >
<a href="..">Home</a>
</li>
<li >
<a href="../about/">About</a>
</li>
<li class="active">
<a href="./">Introduction</a>
</li>
<li >
<a href="../quickstart/">Quick Start</a>
</li>
<li >
<a href="../understanding/">Understanding Vim</a>
</li>
<li >
<a href="../references/">References</a>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li >
<a rel="prev" href="../about/">
<i class="fas fa-arrow-left"></i> Previous
</a>
</li>
<li >
<a rel="next" href="../quickstart/">
Next <i class="fas fa-arrow-right"></i>
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary">
<ul class="nav bs-sidenav">
<li class="first-level active"><a href="#introduction">Introduction</a></li>
<li class="second-level"><a href="#why-choose-vim-for-a-software-documentation-project">Why Choose Vim for a Software Documentation Project?</a></li>
<li class="second-level"><a href="#audience">Audience</a></li>
<li class="second-level"><a href="#appearance">Appearance</a></li>
<li class="second-level"><a href="#our-experience">Our Experience</a></li>
<li class="first-level "><a href="#general-warnings">General Warnings</a></li>
<li class="first-level "><a href="#equipment-and-supplies">Equipment and Supplies</a></li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<h1 id="introduction">Introduction</h1>
<h6>Alaina, Logan</h6>
<h2 id="why-choose-vim-for-a-software-documentation-project">Why Choose Vim for a Software Documentation Project?</h2>
<p>For our software documentation project we chose to write documentation for Vim. Vim is a text editor - not a text editor as would be used by storybook authors or to write papers for English class, but a text editor used by programmers. </p>
<p>Among the Computer Science world, there is a lot of appeal in using Vim because it allows a programmer to navigate quickly and efficiently among their code without the use of the oh-so-inefficient mouse. Vim provides handy ways for inserting, changing, and deleting text. It also contains a variety of keyboard shortcuts that can make coding or doing repeated tasks on text or groups of text lightning-fast.</p>
<p>However, Vim is also infamous for having an incredibly steep learning curve. It can often seem unintuitive to the new user, since most of Vim’s keyboard shortcuts are unlike the keyboard shortcuts of any “traditional” text editor. For instance, control + c for copy, control + v for paste, and control + s for save do not function to copy, paste, or save text in Vim. Instead, Vim has its own unique collection of shortcuts, or “commands”, whose functions are dependent on the current “mode”. Some commands are prefixed with a colon (“:”), while others are simply bound to a single key.</p>
<p>One member of our group was already familiar with Vim when we began the project. The rest of us had to buckle down and learn how to use this text editor before we began writing our documentation. In a few CS classes at Utah State University, teachers and students have made jokes about opening Vim and than being unable to exit (thus becoming stuck in the text editor and—perhaps incapable of exiting the program in order to use a browser to google a solution—having to shut down their computer just to exit Vim! We started by learning how to exit Vim and insert text, then gradually moved on to the more fancy tasks—such as searching and replacing text, copying and pasting text, and navigating a Vim document the way a programmer would. Most of this learning was through trial-and-error, though there exist many other online resources such as Youtube tutorials and web forums, dedicated to learning Vim.</p>
<h2 id="audience">Audience</h2>
<p>During the planning stages of this project we decided to cater our documentation to computer scientists, specifically targeting those who have little to no previous knowledge of using Vim. If we had chosen an audience with a little more experience we could have thrown around some more jargon, but as our choice was to build our manual to serve as an introductory course of sorts we purposefully keep the jargon to a minimum in the beginning, and ramp up as we compound on previous topics.</p>
<p>We also know that people who are learning Vim for the first time are likely to get frustrated because of its steep learning curve. We kept in mind that the typical audience searching for the type of manual we provide is composed of fellow tech people, rather than other non-technical professionals. This allowed us to keep more of a straightforward, light, and casual tone throughout the document which most readers of technical documentation would be familiar with. For example, we used exclamation points in “If you see something like this, you are good to go!” and made it seem like we were there with the user by using statements like, “For now, let’s practice adding some text to Vim.”</p>
<p>We also knew that we would be able to use plenty of visuals in our documentation (i.e., screenshots, videos, tables), as screenshots of a terminal would make sense to those working in a tech-related field.</p>
<p>Keeping in mind the typical reader, our manual includes only the necessities of using Vim, with some previews into the advanced concepts. Most people who want to learn to use Vim are not going to be starting with these advanced concepts, so we demonstrated basic tasks such as opening files, inserting text, navigating the document, and installing Vim. Adding such instructions is effective, as it provides our audience with a single reference of the basics in one place. Those of us learning Vim as we compiled our documentation decided that these concepts would have been the most helpful as we started out.</p>
<h2 id="appearance">Appearance</h2>
<p>The software documentation that we wrote is formatted using Markdown. We decided to compile the documentation into a website using Mkdocs, which made it easy to streamline our formatting process. Because we used Markdown we didn’t have to remember to change the fonts and formats for our headings and text — we just let a stylesheet standardize our fonts, colors, alignment, and design. This was a much easier method to collaborate, since it would have been more difficult to format something in a word processor with 5 of us editing the documentation at different times. It was also good practice for us to use some Computer Science type skills, because most modern software documentation is usually presented as a website or blog, and not as a physical document. </p>
<p>We chose the styles that we did with the simple reasoning that they were pleasing to look at. The styles were also minimalist in design, making the reader’s job of focusing on the contents of the document easier.</p>
<h2 id="our-experience">Our Experience</h2>
<p>Next time we would probably make decisions faster and get done a little earlier. A lot of time was spent learning Vim while concurrently deciding how to organize the document, the content, and making assignments to group members. It often felt there was less time and organization on the days that we didn’t have class and met as a group to work on writing each task and capability.</p>
<p>While it was typically a difficult process overall, we all (hopefully) enjoyed learning Vim. Or, at least, we are all happy to be more familiar with it — and, especially, know how to exit it. </p>
<p>Since there are so many different things that you can do with Vim, it was difficult to decide just how much of Vim we were going to cover in our documentation. We also had to decide if we wanted to write a tutorial for our documentation, or if we just wanted to include the information and then let the users try the commands by themselves. We did use examples (with example text) for the users to be able to see how Vim would appear during certain steps of the process, but we did not do a full-scale tutorial. It would have been nice to build a cohesive, full-scale tutorial to walk our users through, but it ultimately would have made doing group work difficult in our short span of time and busy schedules.</p>
<h1 id="general-warnings">General Warnings</h1>
<h6>Eric</h6>
<p>Vim is a very efficient text editor when a significant amount of time is dedicated to learning its features. Until then, proficiency will come slowly, and with consistent practice. Be patient with yourself as you learn the ins and outs of Vim, and try to learn and use a few new features every day. </p>
<h1 id="equipment-and-supplies">Equipment and Supplies</h1>
<h6>Eric</h6>
<p>In order to use Vim, a computer is required with either Linux, MacOS, or Windows installed. If Vim is not already installed (<a href="../quickstart/">see Quickstart</a>), then an internet connection is required for install.</p></div>
</div>
<footer class="col-md-12 text-center">
<hr>
<p>
<small>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</small>
</p>
</footer>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script src="../js/bootstrap-3.0.3.min.js"></script>
<script src="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.18.0/build/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
<script>var base_url = ".."</script>
<script src="../js/base.js"></script>
<div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">×</span><span class="sr-only">Close</span></button>
</div>
<div class="modal-body">
<table class="table">
<thead>
<tr>
<th style="width: 20%;">Keys</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="help shortcut"><kbd>?</kbd></td>
<td>Open this help</td>
</tr>
<tr>
<td class="next shortcut"><kbd>n</kbd></td>
<td>Next page</td>
</tr>
<tr>
<td class="prev shortcut"><kbd>p</kbd></td>
<td>Previous page</td>
</tr>
<tr>
<td class="search shortcut"><kbd>s</kbd></td>
<td>Search</td>
</tr>
</tbody>
</table>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>
|
