Reframe CLI, revise quickstart, and reorganize tutorials #849

awwad · 2019-04-04T21:18:39Z

This PR:

correctly frames the CLI's current state as a tutorial toy.
provides a friendlier quickstart that puts what it's doing into perspective and guides you to next steps.
provides a better sense of what each tutorial/quickstart doc is for.
makes the getting started page slightly more friendly.
combines the two CLI docs, CLI.md and CLI_EXAMPLES.md
clarifies some installation instructions
other minor tweaks to the quickstart and CLI docs

The larger task this PR is part of is Issue #808.

awwad · 2019-04-04T21:24:03Z

CLI.md and CLI_EXAMPLES.md are really doing the same thing and should probably be merged into a single file: CLI_EXAMPLES.md, either in this PR or a later PR.

- correctly frame the CLI's current state as a tutorial toy. - provide a friendlier quickstart that puts what it's doing into perspective and guides you to next steps. - provide a better sense of what each tutorial/quickstart doc is for. - make the getting started page slightly more friendly. Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

lukpueh

I think your changes/additions to the quickstart guide are really good (left a few minor comments inline). The overall structure of the various documents can still be improved as you point out aptly in #808.

lukpueh · 2019-04-08T10:18:00Z

docs/QUICKSTART.md

+
+Unlike the underlying TUF modules that the CLI uses, the CLI itself is a bit
+bare-bones.  Using the CLI is the easiest way to familiarize yourself with
+how TUF works, however.  It will serve as a very basic update system and use


...? I think this is missing the end of the sentence.

Thanks. ^_^

lukpueh · 2019-04-08T10:25:11Z

docs/QUICKSTART.md

-`tufclient` directories are created in the current working directory.
+**Step (0)** - Make sure TUF is installed
+
+See the [installation instructions for TUF](docs/INSTALLATION.rst).


We are in the same directory INSTALLATION.rst. Remove docs form relative path or use absolute path.

Also, would it be bad to just provide the snippet here? So that quickstarters don't have to go through INSTALLATION.rst?

pip install tuf securesystemslib[crypto,pynacl]

They do need to go through the installation instructions to install TUF. Prior text was a bit misleading in that it suggested that they only needed to run the ssl install. In any case, that step is listed two lines down, to emphasize it, since it would otherwise be optional.

But isn't the line I'm suggesting all that's required for the quick start?

No, you need TUF installed.

Simplified. Installing pip produces everything you need already on a basic Ubuntu platform, so I didn't delve into python-dev or libssl-dev, etc. Just provided the single command in the QUICKSTART.

python-dev or libssl-dev

To contextualize, you need this to build the native support for the openssl backend. I think it's better to keep this from becoming a transient dependency as that may change at some point in the future...

I'm not clear on your suggestion, sorry: are you saying that we should avoid implicitly requiring that libssl-dev or similar packages be installed, or that we should avoid advising it explicitly since it may not be necessary? (Or something else?)

oh, the opposite. I understood that you were advising to remove these deps because something else is pulling them in. I'd rather have them explicitly just in case this is not the default in the future.

Currently, those requirements are now only in the collaborator docs, not in the installation docs. I was wondering if I should move them back into the installation docs. You're suggesting that we include them, which is good to hear, so I'll pull them back in to the natural place to put them (the installation instructions). I'll frame them as as-necessary installations, I guess, to try to keep things simple.

That's beyond the scope of this PR, so I'll just do that in the next one, but for this PR, I'll split the difference in QUICKSTART.md in anticipation of that change....

lukpueh · 2019-04-08T10:31:44Z

docs/QUICKSTART.md

 ```

-**Step (4)** - Fetch a target file from the repo.  The client downloads
-any required metadata and the requested target file.
+**Step (4)** - Obtain and verify the `testfile` update on a client.


minuscule nit-pick: You end some heading sentences with a period and other not.

lukpueh · 2019-04-08T10:42:23Z

docs/GETTING_STARTED.rst

- `CLI <CLI.md>`_
- `CLI Usage Examples <CLI_EXAMPLES.md>`_
- `Tutorial <TUTORIAL.md>`_
+- Beginner Tutorials (using the basic command-line interface): `Quickstart <QUICKSTART.md>`_; `CLI Tutorial <CLI.md>`_; `CLI Further Examples <CLI_EXAMPLES.md>`_


The long line looks a little daunting now. I would leave QUICKSTART.md separate and see if the cli tutorials could be combined, or restructured? From a quick glance, CLI.md looks like a documentation of the interface, whereas CLI_EXAMPLES.md looks like a slightly more in-depth version of QUICKSTART.md.

Fixed, and I've now combined the two CLI documents.

lukpueh · 2019-04-08T10:43:29Z

docs/GETTING_STARTED.rst

- `CLI Usage Examples <CLI_EXAMPLES.md>`_
- `Tutorial <TUTORIAL.md>`_
+- Beginner Tutorials (using the basic command-line interface): `Quickstart <QUICKSTART.md>`_; `CLI Tutorial <CLI.md>`_; `CLI Further Examples <CLI_EXAMPLES.md>`_
+- `Advanced Tutorial <TUTORIAL.md>`_


If you call it advanced tutorial here, which I think is a good idea, you maybe also want to call it that in the document heading?

Fixed there and elsewhere, thanks.

in the QUICKSTARD.md Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

trishankatdatadog · 2019-04-08T17:36:44Z

@awwad It's because cryptography manylinux1 wheel bundles its own copy of OpenSSL, unless you use something glib-c incompatible, like Alpine

Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

awwad added the documentation Documentation of the project as well as procedural documentation label Apr 4, 2019

awwad assigned lukpueh, SantiagoTorres and adityasaky Apr 4, 2019

awwad force-pushed the clarify_role_of_cli branch from f1af517 to c5b4306 Compare April 4, 2019 21:22

awwad force-pushed the clarify_role_of_cli branch from c5b4306 to 907186e Compare April 5, 2019 17:44

lukpueh reviewed Apr 8, 2019

View reviewed changes

awwad added 2 commits April 8, 2019 11:49

minor DOC: fix unfinished sentence, some punctuation

5a94d5d

in the QUICKSTARD.md Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

DOC: collapse CLI_EXAMPLES.md into CLI.md

1f3e5b6

Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

awwad force-pushed the clarify_role_of_cli branch from 46d3c95 to 1f3e5b6 Compare April 8, 2019 15:54

awwad added 2 commits April 8, 2019 11:56

minor DOC: label the advanced tutorial as such

ed6acd4

Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

DOC: simplify installation instructions in QUICKSTART

2af4d3f

Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

DOC: cover possible environment requirements in QUICKSTART

67dd649

Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

awwad merged commit 4f01a31 into develop Apr 8, 2019

awwad deleted the clarify_role_of_cli branch May 2, 2019 16:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reframe CLI, revise quickstart, and reorganize tutorials #849

Reframe CLI, revise quickstart, and reorganize tutorials #849

awwad commented Apr 4, 2019 •

edited

awwad commented Apr 4, 2019 •

edited

lukpueh left a comment

lukpueh Apr 8, 2019

awwad Apr 8, 2019

lukpueh Apr 8, 2019

lukpueh Apr 8, 2019

awwad Apr 8, 2019

lukpueh Apr 8, 2019

awwad Apr 8, 2019

awwad Apr 8, 2019

SantiagoTorres Apr 8, 2019

awwad Apr 8, 2019

SantiagoTorres Apr 8, 2019

awwad Apr 8, 2019

lukpueh Apr 8, 2019

awwad Apr 8, 2019

lukpueh Apr 8, 2019

awwad Apr 8, 2019

lukpueh Apr 8, 2019

awwad Apr 8, 2019

trishankatdatadog commented Apr 8, 2019

Reframe CLI, revise quickstart, and reorganize tutorials #849

Reframe CLI, revise quickstart, and reorganize tutorials #849

Conversation

awwad commented Apr 4, 2019 • edited

awwad commented Apr 4, 2019 • edited

lukpueh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

trishankatdatadog commented Apr 8, 2019

awwad commented Apr 4, 2019 •

edited

awwad commented Apr 4, 2019 •

edited