Restructure Quickstart docs to get from zero to hacking faster. #6157

m-renaud · 2019-07-25T04:28:08Z

I've made a few changes to the structure of the "Quickstart" section of the user guide so that someone new to Cabal can get to a Haskell package they can build and run sooner. Additionally, changes are made given the new Executable default for cabal init when non-interactive is used.

Changes include:

Instructions start from an empty directory instead of "assuming we have a project directory and already have a Haskell module or two".
- Rationale: If someone is reading the quickstart guide its unlikely they already know what a project directory looks like, and are unlikely have any modules already. They instead are probably looking for minimal instructions for how to get started with Haskell+Cabal.
TL;DR; section at the top
- Rationale: Sometimes you don't want to read a bunch of words, you just want a command to copy and paste into your terminal. This provides that.

This partially addresses #6194.

[ci skip]

Please include the following checklist in your PR:

Patches conform to the coding conventions.
Any changes that could be relevant to users have been recorded in the changelog.
The documentation has been updated, if necessary.
If the change is docs-only, [ci skip] is used to avoid triggering the build bots.

Please also shortly describe how you tested your change. Bonus points for added tests!

vrom911

Nice work on improving docs!

Cabal/doc/developing-packages.rst

vrom911

Very nice improvements to the docs! Thanks, @m-renaud 👍

phadej · 2019-07-28T08:09:19Z

Note that audience have changed, from ”I cloned a Haskell repository and want to make a change” to ”I want to write a Haskell package”. IMHO former is more common, and latter is not something every user may even need. Given`cabal run`, and `cabal repl` there are simpler ways to start own experiments than creating own package. And creating own package is described (or should be) in ”development package”. TL;DR don’t forget about the people, ”I cloned a package, what and how I can do next?”

…

On 28 Jul 2019, at 7.45, Veronika Romashkina ***@***.***> wrote: @vrom911 approved this pull request. Very nice improvements to the docs! Thanks, @m-renaud 👍 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

m-renaud · 2019-07-29T15:46:48Z

Hey @phadej, thanks for the feedback!

Note that audience have changed, from ”I cloned a Haskell repository and want to make a change” to ”I want to write a Haskell package”.

I don't think this is true, the audience was never for those cloning a Haskell repo. The previous wording said things like "Lets assume we have created a project directory and already have a Haskell module or two.", if you're at the point where you've found a Haskell repo you want to hack on you almost certainly know about cabal build and cabal run. Also, if they did just clone a repo there would already be a .cabal file and so the whole cabal init section wouldn't be relevant (which is the majority of the changes I've made in this PR). It was already targeted towards "I want to write a Haskell package" but had previous assumptions about the users knowledge which docs should never do (unless explicitly called out).

IMHO former is more common, and latter is not something every user may even need.

I'm going to challenge this assumption, I wouldn't call myself a Haskell newbie by any means, and I've can cabal init to set up a directory for trying something small out orders of magnitude more times than I've cloned well established Haskell repos. It may be the case that for well versed Haskellers cloning an existing project and then hacking on that is the more common use case, and I admit that it is true that the current Haskell community consists of a high proportion of "experts", but the "Quickstart" docs should assume the opposite.

TL;DR don’t forget about the people, ”I cloned a package, what and how I can do next?”

For sure, this is the other common way to "get started" and doesn't really have any docs for it currently afaik. I still think the "Hey, I just learned about Haskell, I want to run through some tutorials, how do I create a file and set up some dependencies that I need?" should be the primary focus if we ever want to grow the Haskell community.

In general I think the overall docs need to be restructured to put these two "I'm just getting started"/quickstart sections much closer to the beginning. I have a bunch of ideas for improving the docs, wasn't sure the best way to solicit feedback before making a bunch of changes though, maybe open an RFC issue?

tom-audm · 2019-07-29T16:01:30Z

I respectfully don't understand the purpose of telling newcomers to cabal init --non-interactive in an empty directory:

If you're just doing it in an empty directory, you're not solving the case of "I just want a .cabal file so that I can cabal v2-repl," since there are no dependencies you're satisfying - you could simply ghci
If the user actually is creating a package, don't they want to specify things like license, author name, is this a library or executable, etc? Sensible defaults are given in interactive mode, too.

It would make most sense to me for the quickstart guide to either be the "what do I do with this cloned repo" that @phadej suggests, or to give the user hand-holding with cabal init.

m-renaud · 2020-03-21T20:08:21Z

Hey @tom-audm and @phadej, reviving this PR due to forced free time :P There are several changes in this PR and I'd like to get as many of them merged in as possible. I'm going to start by attempting to answer the questions you've raised:

If you're just doing it in an empty directory...you could simply ghci

Neither using ghci nor cabal v2-repl create a .cabal file for you to add dependencies, so as soon as you want to use anything beyond what's in base (which is almost immediately because Haskell has a relatively small base library and relies on Hackage packages a lot), you need to figure out how to create a .cabal file anyways, so might as well start with a command that sets the environment up for you.

If the user actually is creating a package, don't they want to specify things like license, author name, is this a library or executable, etc?

If you're a library author who's planning on uploading things to hackage than I think you're beyond the newcomer level and thus are already familiar with the tools. On the other hand, if you're a newcomer to Haskell all you want to know is "How do I get an environment up and running as soon as possible?" In general Haskell's docs throughout the ecosystem aren't the most newcomer friendly. If you look at other languages, for example the Rust - Getting started page, it lays out going from zero to a functioning project with dependencies in a very concise way.

Reading through your comments again it sounds like these are the concerns you have:

Previously this content only covered the ”I cloned a package, what and how I can do next?” (non-newcomer workflow), and now it only covers "Run cabal init --non-interactive to get a project set-up from scratch" (newcomer to the language workflow).
- Proposal: Create two sub-sections: 1) Project from scratch, 2) Existing project, how do I hack on it?
Why switch from interactive to non-interactive? We should let users know all of the options and configuration that is available.
- Re-reading through the changes I made I do call out both interactive and non-interactive and describe what they do. Could you leave comments on the actual code changes and request specific changes so that it's actionable?

I think the major source of misalignment comes from me viewing the "Quickstart" as a "Haskell newcomer quickstart", and (my understanding of) your view as the "Quckstart" to "I want to develop a Haskell package to put on Hackage". The solution to this may be to create a separate "Getting Started" page in the Cabal docs (Proposal: "Section 0. Quickstart" or "Section 0. Getting started with Haskell and Cabal") which mirrors the "Rust - Getting started" page. If this sounds like a reasonable path forward I can put together a PR for comments.

Let me know what you think!

@23Skidoo for thoughts/comments as well.

phadej

Looks fine. Some nitpicking inline.

Cabal/doc/developing-packages.rst

phadej · 2020-03-21T20:25:19Z

Cabal/doc/developing-packages.rst


-Every project needs a name, we'll call this example "proglet".
+**TL;DR;** ``mkdir proglet && cd proglet && cabal init --non-interactive && cabal run``


isn't --non-interactive default now?

Yup, updated, and also explicitly added proglet as the argument to cabal run.

phadej · 2020-03-21T20:26:00Z

Cabal/doc/developing-packages.rst

-Using "cabal init"
------------------
+The ``cabal init`` command creates the necessary files for a Cabal package,
+it has both an ``--interactive`` (default) and ``--non-interactive``


haven't these reversed?

Since I wrote this, yes. Move the (default) to after non-interactive.

phadej · 2020-03-21T20:27:15Z

Cabal/doc/developing-packages.rst

+   ...
+   Linking /path/to/proglet ...
+
+   $ cabal run


I'd add the executable name. It's nice that cabal run works without it, but that is rare special case.

phadej · 2020-03-21T20:27:34Z

Cabal/doc/developing-packages.rst

+   Linking /path/to/proglet ...
+
+   $ cabal run
+   <Stuff about resolving dependencies, build profile, compliling, linking>


phadej · 2020-03-21T20:28:52Z

Cabal/doc/developing-packages.rst

+
+It is assumed that all the files that make up a package live under a common
+project root directory (apart from external dependencies). This simple
+example will have all the project files in one directory, but most packages


package files

phadej · 2020-03-21T20:29:02Z

Cabal/doc/developing-packages.rst

+example will have all the project files in one directory, but most packages
+will use one or more subdirectories.
+
+Cabal needs two extra files in the project's root directory:


Cabal/doc/developing-packages.rst

phadej · 2020-03-21T20:36:01Z

I'll change non-interactive init to not pick any license if not explicitly asked by a flag. You should adjust the text accordingly.

The side-effect of above would be that these test projects won't be as such uploadable to Hackage.

If you're a library author who's planning on uploading things to hackage than I think you're beyond the newcomer level and thus are already familiar with the tools.

From my experience, that is not true. People want to upload their stuff to Hackage almost as soon as they get something working, sometimes even a bit before that.

m-renaud

I think my most recent commit addresses your comments, lmk if I missed anything!

Cabal/doc/developing-packages.rst

m-renaud · 2020-03-21T21:26:25Z

Cabal/doc/developing-packages.rst


-Every project needs a name, we'll call this example "proglet".
+**TL;DR;** ``mkdir proglet && cd proglet && cabal init --non-interactive && cabal run``


Yup, updated, and also explicitly added proglet as the argument to cabal run.

m-renaud · 2020-03-21T21:37:15Z

Cabal/doc/developing-packages.rst

-Using "cabal init"
------------------
+The ``cabal init`` command creates the necessary files for a Cabal package,
+it has both an ``--interactive`` (default) and ``--non-interactive``


Since I wrote this, yes. Move the (default) to after non-interactive.

m-renaud · 2020-03-21T21:38:47Z

Cabal/doc/developing-packages.rst

+   ...
+   Linking /path/to/proglet ...
+
+   $ cabal run


m-renaud · 2020-03-21T21:39:09Z

Cabal/doc/developing-packages.rst

+   Linking /path/to/proglet ...
+
+   $ cabal run
+   <Stuff about resolving dependencies, build profile, compliling, linking>


m-renaud · 2020-03-21T21:41:27Z

Cabal/doc/developing-packages.rst

+
+It is assumed that all the files that make up a package live under a common
+project root directory (apart from external dependencies). This simple
+example will have all the project files in one directory, but most packages


m-renaud · 2020-03-21T21:41:38Z

Cabal/doc/developing-packages.rst

+example will have all the project files in one directory, but most packages
+will use one or more subdirectories.
+
+Cabal needs two extra files in the project's root directory:


Cabal/doc/developing-packages.rst

m-renaud · 2020-03-21T21:49:52Z

I'll change non-interactive init to not pick any license if not explicitly asked by a flag. You should adjust the text accordingly.

SG. Alternatively I can submit this and you can make the doc change at the same time you change the behaviour (my preference to keep doc updates with code changes).

From my experience, that is not true

Fair enough. I guess I was referring to folks who are just discovering haskell, it's unlikely they'll be uploading to hackage right away, but your point still stands. lmk if you have suggestions for wording tweaks around this.

m-renaud · 2020-03-22T01:12:44Z

Alright, I think I've addressed all of your comments. Let me know if there's anything else, otherwise can you merge this into master?

fgaz · 2021-02-02T15:44:37Z

Why did this stall? Is it still up to date?

- Combine interactive and non-interactive sections together, and mention which is the default. - Add output from 'ls' command. - Add note about Setup.hs being optional - Small formatting changes. [ci skip]

[ci skip]

m-renaud · 2021-04-29T03:37:33Z

Just rebased but looks like files have changed locations since this was started.

m-renaud · 2021-04-29T03:48:04Z

Alright, fixed. The rebase blew away the comment anchors though unfortunately.

m-renaud · 2021-04-29T03:48:28Z

@phadej PTAL when you have a chance.

Mikolaj · 2021-05-06T21:31:41Z

Let me take over the review from @phadej. Unless @emilypi or @fgaz would like to review instead?

Mikolaj

I've reviewed rather shallowly, but apart of a few nitpicks it LGTM and based on the in-depth discussion by the other esteemed reviewers I'd love to see this merged ASAP (sorry for the prolonged process --- the kind souls helping with cabal are smeared rather thin).

doc/developing-packages.rst

Mikolaj · 2021-05-25T12:34:54Z

@m-renaud: do my nitpicks make sense? Let's get this merged.

m-renaud · 2021-05-25T13:14:51Z

Hey @Mikolaj! Yes, thank you for the review, sorry for the slow reply here; I'll try to get the changes out this week. It could definitely use some active voice rewording (read: more direct) throughout, but I can do that in a follow up.

Mikolaj · 2021-08-11T12:28:29Z

Hi @m-renaud: I see there crept up conflicts since we last looked at this PR and I'm guilty of adding yet another conflict in #7526 (hurried up in order to backport to 3.6 in time; let's hope we can get this one to 3.6 as well).

Would you like to resolve the conflicts or should I do that?

m-renaud · 2021-08-16T00:15:45Z

Hey @Mikolaj! I'm on vacation until next Monday but can resolve any merge conflicts next week, if that's an acceptable timeframe :)

Edit: next Monday

Mikolaj · 2021-08-16T08:23:20Z

@m-renaud: in that case, please don't think about it and enjoy your vacation. :) I will resolve conflicts and if we happen to merge this PR (perhaps even to 3.6) before your return, we can always adjust with your feedback for a point release, after you return.

Mikolaj · 2021-08-16T13:04:11Z

The rebased PR is at #7551. Whomever feels like it, please kindly review.

@m-renaud

…tarted Restructure Getting Started docs to get to a running program faster. This is rebased (with resolved conflicts) version of #6157 by @m-renaud .

Mikolaj · 2021-09-07T10:52:11Z

This was merged as #7551. Thank you, @m-renaud and everybody!

m-renaud requested review from 23Skidoo and hvr July 25, 2019 04:28

vrom911 reviewed Jul 25, 2019

View reviewed changes

Cabal/doc/developing-packages.rst Outdated Show resolved Hide resolved

Cabal/doc/developing-packages.rst Outdated Show resolved Hide resolved

Cabal/doc/developing-packages.rst Outdated Show resolved Hide resolved

Cabal/doc/developing-packages.rst Outdated Show resolved Hide resolved

m-renaud requested a review from vrom911 July 26, 2019 21:16

vrom911 approved these changes Jul 28, 2019

View reviewed changes

m-renaud mentioned this pull request Mar 21, 2020

RFC: Improve and restructure Cabal user guide #6194

Open

phadej reviewed Mar 21, 2020

View reviewed changes

m-renaud commented Mar 21, 2020

View reviewed changes

m-renaud requested review from phadej and removed request for 23Skidoo and hvr March 22, 2020 01:13

m-renaud added the documentation label May 7, 2020

m-renaud mentioned this pull request May 7, 2020

cabal init not interactive by default in 3.0 #6761

Merged

3 tasks

m-renaud added 5 commits April 28, 2021 20:34

Restructure Getting Started docs to get to a running program faster.

294bda9

Address @vrom911's comments.

191cc14

- Combine interactive and non-interactive sections together, and mention which is the default. - Add output from 'ls' command. - Add note about Setup.hs being optional - Small formatting changes. [ci skip]

Address @phadej's review comments.

542759b

Few more small tweaks.

53354e9

[ci skip]

Remove a couple more errenous references to "project".

99b74ce

[ci skip]

m-renaud force-pushed the mrenaud-docs-getting-started branch from febd930 to 99b74ce Compare April 29, 2021 03:35

m-renaud added 2 commits April 28, 2021 20:45

Apply changes to new file location

74a1fbb

Fix title

1300f2b

Fix typo

5f4aa96

Mikolaj self-requested a review May 6, 2021 21:31

Mikolaj requested changes May 11, 2021

View reviewed changes

Mikolaj approved these changes May 25, 2021

View reviewed changes

m-renaud added 2 commits May 25, 2021 07:35

Address review comments.

e31216c

Remove merge artifact.

ca3ef13

emilypi approved these changes May 25, 2021

View reviewed changes

Mikolaj removed the request for review from phadej August 10, 2021 22:05

Mikolaj mentioned this pull request Aug 16, 2021

Restructure Getting Started docs to get to a running program faster. #7551

Merged

Mikolaj closed this Sep 7, 2021


		Every project needs a name, we'll call this example "proglet".
		TL;DR; ``mkdir proglet && cd proglet && cabal init --non-interactive && cabal run``

Restructure Quickstart docs to get from zero to hacking faster. #6157

Restructure Quickstart docs to get from zero to hacking faster. #6157

Conversation

m-renaud commented Jul 25, 2019 • edited Loading

vrom911 left a comment

Choose a reason for hiding this comment

vrom911 left a comment

Choose a reason for hiding this comment

phadej commented Jul 28, 2019 via email

m-renaud commented Jul 29, 2019

tom-audm commented Jul 29, 2019

m-renaud commented Mar 21, 2020 • edited Loading

phadej 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

phadej commented Mar 21, 2020

m-renaud 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

m-renaud commented Mar 21, 2020

m-renaud commented Mar 22, 2020

fgaz commented Feb 2, 2021

m-renaud commented Apr 29, 2021

m-renaud commented Apr 29, 2021

m-renaud commented Apr 29, 2021

Mikolaj commented May 6, 2021

Mikolaj left a comment

Choose a reason for hiding this comment

Mikolaj commented May 25, 2021

m-renaud commented May 25, 2021

Mikolaj commented Aug 11, 2021

m-renaud commented Aug 16, 2021 • edited Loading

Mikolaj commented Aug 16, 2021

Mikolaj commented Aug 16, 2021

Mikolaj commented Sep 7, 2021

m-renaud commented Jul 25, 2019 •

edited

Loading

m-renaud commented Mar 21, 2020 •

edited

Loading

m-renaud commented Aug 16, 2021 •

edited

Loading