diff options
| author | Elizabeth Alexander Hunt <me@liz.coffee> | 2026-07-02 11:55:17 -0700 |
|---|---|---|
| committer | Elizabeth Alexander Hunt <me@liz.coffee> | 2026-07-02 11:55:17 -0700 |
| commit | 6bf4b90c90f15f4ab60833bddf5b5756d1a6b1f6 (patch) | |
| tree | ed97e39ec77c5231ffd2c394493e68d00ddac5a4 /Homework/engl3085/Technical-Comm/vim-docs-for-3085/site/intro | |
| download | misc-undergrad-main.tar.gz misc-undergrad-main.zip | |
Diffstat (limited to 'Homework/engl3085/Technical-Comm/vim-docs-for-3085/site/intro')
| -rw-r--r-- | Homework/engl3085/Technical-Comm/vim-docs-for-3085/site/intro/index.html | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/Homework/engl3085/Technical-Comm/vim-docs-for-3085/site/intro/index.html b/Homework/engl3085/Technical-Comm/vim-docs-for-3085/site/intro/index.html new file mode 100644 index 0000000..9f0e0bd --- /dev/null +++ b/Homework/engl3085/Technical-Comm/vim-docs-for-3085/site/intro/index.html @@ -0,0 +1,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> |