Reorganizing the documentation

[banacorn]

I know there is #4252, but I think the whole guide (and the documentation) is beyond saving.

I've been using Stack for years, and I like how it always delivers consistent builds 👍.
But to be honest, I still don't know how to use it.
And when I need help, after hopelessly scouring the documentation, I almost always ended up somewhere in Stackoverflow.
The whole experience is just daunting (and I'm too afraid to ask how newcomers feel about this 🙈.)
But I wish I could do more than just complaining.

---

The current documentation is just a pile of articles, without much organization.

We need to restructure the documentation from the user's perspective, and I reckon there are 3 types of users:

• Newcomers who need a guide (a short guide !) on installing Stack and building a simple hello world project
• Users who just wanna lookup some command
• Power users, probably doing some CI/CD stuff

I think Cargo had done a pretty good job on this. We should model our documentation after theirs.

[smichel17]

and I'm too afraid to ask how newcomers feel about this 🙈

Hello, relative newcomer here.

I was recently troubleshooting an issue around compile times. The actual topic is kind of tangential, but I documented the process in detail; maybe it'll be helpful in figuring out what type of roadblocks people actually hit (and particularly, in what order!) smichel17/yesod-perf-test#1

Assorted thoughts:

• Reading the guide was useful. Don't remove it until something is ready to replace it!

• What I missed the most was reference documentation*, saying what the actual affect of each command is. The short summary produced by stack COMMAND --help doesn't cut it. One page per command (all on one page would be ok too).

  *Note: the cargo docs basically follow this format, although their terms for the sections don't match Divio's.

  • Concrete example: I wanted to know what affect --word-dir .stack-work-devel actually has on the ghc command that gets run at the end of the day. Does it affect the -outputdir (or its parts, like -odir / -hidir)?

• Next, fix --verbosity info is too terse compared to --verbosity debug #5323.

  • Strictly speaking, this isn't a docs issue, but it's an important release valve. When I can't figure out what's happening from the docs, I can look at the debug output (this is how I eventually found the answer to the question above)… but right now enabling -v spits out half a megabyte of logs.

A common thread is exposing key information for me to go look up in the documentation for other tools. I appreciate that writing documentation is difficult and time-consuming, and I am willing to put in the legwork to follow the documentation "upstream" (and I think so are most Haskell developers 😁), but it's very difficult to do when I don't know what I should be looking for yet.

[malteneuss]

I also really like the Cargo docks with its clear separation between newcomer steps, guides, and reference sections, and i would support this initiative. How could we proceed? I propose to start with a small "Getting started" section for newcomers.

[mpilgrem]

Closing this issue as, since it was opened, Stack's online documentation has been extensively reorganized.

[banacorn]

Thank you!!