Skip to content

Instantly share code, notes, and snippets.

@jkonecny12

jkonecny12/README.md

Last active January 11, 2017 14:48
Show Gist options
  • Save jkonecny12/4bf3d4e34ac8d8073469ff28198b46f9 to your computer and use it in GitHub Desktop.
Save jkonecny12/4bf3d4e34ac8d8073469ff28198b46f9 to your computer and use it in GitHub Desktop.
Download ZIP
simpleline-readme
Raw
README.md

python-simpleline

This is a text UI framework originally it was a part of [Anaconda]
(https://github.com/rhinstaller/anaconda) installer project.

This UI is trying to be simple and easy to use. It is designed to be used with line
based machines and tools (like serial console) so every new line is printed to the
bottom of the screen and then moved to the top. Printed lines are never rewritten!

How to

Best how to learn this library is look to the examples directory here in a project.
Examples can be ran without installing Simpleline to the system. You can test them
by running script run_example.sh.

  1. cd examples
  2. ./run_example.sh example_folder_name

For example:
./run_example.sh basic

Dependencies

This is Python3 only project. It shouldn't be so hard to migrate it to Python2 but
we don't have any use for it now. No special libraries are required to run this
library.

If you want to run tests (make ci), you need to install [Pocketlint]
(https://github.com/rhinstaller/pocketlint).

@snbueno
Copy link

snbueno commented Jan 11, 2017

This is a text UI framework originally it was a part of Anaconda installer project.

Run-on sentence; you've got two independent clauses here that are not linked in any way. Link or separate them. Anaconda installer project also needs to be prepended with the. Try reading the sentence without the modifiers for project and the need for the should become more clear. So:

This is a text UI framework. Originally, it was a part of the Anaconda installer project.

or

This is a text UI framework which was originally part of the Anaconda installer project.

Ok. Moving on.

This UI is trying to be simple and easy to use.

I can't explain why this sounds odd, but it does, because of the is. The wording also makes the sentence seem less professional and more fun, since you make it sound like the UI has personality traits ("simple" and "easy to use"). In technical writing, it's better to sound more detached and, well, technical. So let's rewrite a couple of other sentences in that paragraph as well.

The UI is simple and easy to use. It is designed to be used with line-based
machines and tools (e.g. serial console) so that every new line is
appended to the bottom of the screen. Printed lines are never rewritten!

Next sentence.

Best how to learn this library is look to the examples directory here in a project.

A couple of notes before I fix the errors. The first half of the sentence is a bit tricky, since a lot of infinitives are used in English. here in a project is unnecessary text since the examples are already right there in the project when they check it out. If the examples lived somewhere else, then you could mention where. I mention this because it's important in any writing to only include the important information. Otherwise your readers will start skipping words or just not bother to read it at all. So, let's fix up a couple mistakes:

The best way to learn how to use this library is to view the examples directory.

Next sentence.

Examples can be ran without installing Simpleline to the system.

Just a small tense problem:

Examples can be run without installing Simpleline to the system.

And one more small problem in the next sentence.

You can test them by running script run_example.sh.

There are a couple of ways you can rewrite this, but they all involve you adding an article before script. So we can have:

You can test them by running the script run_example.sh.

or

You can test them by running the run_example.sh script.

All right, that's enough of that sentence.

This is Python3 only project.

Like in one of the above sentences, try reading this without the modifiers for project, and it should become clear that you need an article: Additionally, insert a hyphen between the modifying words so that it's clear these words are to be interpreted as a single term.

This is a Python3-only project.

Next sentence.

It shouldn't be so hard to migrate it to Python2 but we don't have any use for it now.

I can definitely tell you wrote this, because I can imagine you saying this sentence. :) This is fine in casual speech and casual text, but you should aim to sound a little more formal in technical writing. Some things which help -- no contractions, no/very little use of pronouns ("we", "I", "you", etc.). A note on the pronouns, particularly in this sentence -- notice how you use "it" twice in the first half. There is a bit of an unclear antecedent because of this (what exactly is "it" referring to?). You'll want to be careful of that. Technical writing should always strive to be very clear. So how would this be rewritten to sound more formal?

This code should not be difficult to migrate to Python2. Since there is no need from the community, however, it is only compatible with Python3 at the moment.

All right. I hope this helps and explains some things, not only about grammar, but writing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment