Update GUIDE.md doc

[snoyberg]

This is a long user guide doc that I wrote quite a while ago. I'm sure it could be improved significantly now that we have a lot more user experience with where people get tripped up with Stack.

Another possibility: maybe people are getting their information on Stack in other ways, and this document is no longer necessary. I'd appreciate feedback either way on this.

In the meanwhile, I'm going to add a comment to the top of the doc that it deserves getting updated.

[ahidalgob]

I think the --solver option in External Dependencies is out of date. I get Invalid option `--solver', and the previous init command does not suggests such switch (only --omit-packages and --resolver)

$ stack --version
Version 2.1.1, Git revision f612ea85316bbc327a64e4ad8d9f0b150dc12d4b (7648 commits) x86_64 hpack-0.31.2

I guess the same goes for the stack solver section.

Thank you!

[friedbrice]

Similar, but different from @ahidalgob's issue.

In Existing projects > stack init > External Dependencies, stack init --force --solver is accepted as a valid Stack command, but it fails with error when used in conjunction with cabal-install version 2.4.

A work-around is to use cabal install --dry-run to list the results of the dependency solver, and then manually modify your stack.yaml, adding the packages missing from Stackage.

Using Stack version 1.9.3.1, Git revision 43ff632.

[RogueToad]

Not an issue - just thought it worth mentioning that I found the guide very helpful . There's a lot of misinformation around which this helped clear up for me, but bringing it up to date would be nice.

[supermacro]

Hey, I'm new to Stack and found the guide overall really helpful. One thing I did not find in the docs, however, was further info on the distinction between src/Lib.hs and app/Main.hs. I did find this SO post, though which cleared things up for me.

I would be up for opening a PR to include this information somewhere in the docs!

[ronwinn]

Appreciate your effort!
Could you please add information on how to specify where stack new is placing the projects?
At the moment it looks like it creates all projects on the top level of home, which is very impractical imho.
Little details like this are necessary to give newbs the confidence to use the tools without repercussions like having to edit paths in dozens of files to keep the project working if they want to move it to a different location.
So far I could not find this information, so I'm stuck.

[sigvaldm]

Thanks for the guide. Such things are crucial for us who want to get into developing with Haskell. I try to create a new project as described in the quick start, but when I type stack build i get '

Error parsing targets: The specified targets matched no packages.
Perhaps you need to run 'stack init'?

and when I type stack init I get:

 "/home/sigvald/.stack/build-plan/lts-15.5.yaml" (Response {responseStatus = Status {statusCode = 404, statusMessage = "Not Found"}, responseVersion = HTTP/1.1, responseHeaders = [("Connection","keep-alive"),("Content-Length","15"),("Content-Security-Policy","default-src 'none'; style-src 'unsafe-inline'; sandbox"),("Strict-Transport-Security","max-age=31536000"),("X-Content-Type-Options","nosniff"),("X-Frame-Options","deny"),("X-XSS-Protection","1; mode=block"),("Via","1.1 varnish (Varnish/6.0)"),("X-GitHub-Request-Id","4642:2D30:1C693:1ECCB:5E7E2237"),("Accept-Ranges","bytes"),("Date","Fri, 27 Mar 2020 15:56:41 GMT"),("Via","1.1 varnish"),("X-Served-By","cache-osl6535-OSL"),("X-Cache","HIT, MISS"),("X-Cache-Hits","8, 0"),("X-Timer","S1585324601.143096,VS0,VE333"),("Vary","Authorization,Accept-Encoding"),("Access-Control-Allow-Origin","*"),("X-Fastly-Request-ID","926344e902ae05ab09d1e24c6be8a4961cdb421a"),("Expires","Fri, 27 Mar 2020 16:01:41 GMT"),("Source-Age","0")], responseBody = (), responseCookieJar = CJ {expose = []}, responseClose' = ResponseClose})

Any advice?

[friedbrice]

@sigvaldm Can you put your project (or a minimal example) on github and link to it?

[sigvaldm]

@friedbrice: Think I just found the error myself. I had stack 1.7. Doing stack upgrade and then trying stack init and stack build seemed to do the trick. (My project is just the first thing I got when running stack new project. Just trying this out. Looks like a nice tool.)

[mostalive]

Came to the guide from a search. Coming back to haskell / stack after a while. The guide seems useful , thanks. I didn't know about package.yaml, that helped (I did stack new myproject hspec - that creates a .cabal file, not package. yaml. It doesn't rebuild when only a test changes. It took a while to figure out, and I can't find the relevant issues for stack that I saw late last night. Will try again later).

[smichel17]

Another possibility: maybe people are getting their information on Stack in other ways, and this document is no longer necessary. I'd appreciate feedback either way on this.

The guide is still where I looked. If there are other, better places, I'd appreciate if the docs would link to them.

[malteneuss]

In #5457 i've seen the initiative to reorganize the Stack documentation to a format similar to Rust's Cargo build tool docs with a clear separation between newcomer steps, guides, and reference sections. Would that be of interest? I could start with a small refactoring towards a separate "Getting started" section for newcomers.

[mpilgrem]

@malteneuss, my own priorities in respect of Stack's existing online documentation have been its accuracy, completeness, consistency, and relevancy - and probably broadly in that pecking order. I've put 'structure' and 'discoverability' towards the back of the queue, partly because the current 'search' functionality of the online documentation is pretty good and partly because the existing content is quite 'structured' - that is, the debate is not so much about 'structured versus unstructured' but 'how best to structure?'.

However, I have had 'structure' in mind, and, to some extent, my own refactoring of, and additions to, the online documentation in recent months has reflected your intent:

• The short Home page still provides the 'Quick Start' guide and the clear link to the intoductory part of the User's Guide. My objective is that the Home page should be written in the simplest language and try to assume very little prior knowledge on the part of the reader - while remaining 'no longer than necessary'.

• the existing User's guide has been divided between an 'introductory' part for new Stack users (this is, essentially, the 'Getting Started' tutorial, followed by some other introductory material) and an 'advanced' part. The former retains its tutorial-like approach, the latter is more 'reference guide' in its organisation and approach. There is certainly a debate to be had about whether all of the material in the 'introductory' part is genuinely introductory. I would be interested in your views: when you look at the 'User guide (introductory)' with 'Getting Started' in mind, what would you change?

• There is also a debate to be had about how 'introductory' the introductory material should be - what is the reader assumed to know, or not know, already? I am all for the push to make Haskell 'accessible', but I think it would help greatly with coordination of effort to have a shared vision about who that hypothetical 'newcomer' is. For example, are they somebody about to embark on undergraduate studies in computer science at university, who now has 'Haskell' on their pre-university reading list? Are they a curious young teenager who has been taught some Python at school, and is now building on the interest that has sparked? I suspect it is more the former than the latter. In some respects, I think having a common understanding of 'who the material is aimed at' is more important than any particular choice of hypothetical 'newcomer'.

• outside of the two parts of the User's guide, the topic-specific guidance is a mix of tutorial-like and reference-like, depending on the subject matter. I think you can't be prescriptive about form, but you can try to aid the reader by being consistent in terminology (the old adage of 'if you have three bananas, call them three bananas, not two bananas and one elongated yellow fruit'). To that end, I added the Glossary and have been trying to conform the documentation to a single 'vocabulary'.

• The documentation is now, I think, at least tolerably complete; I think every command in Stack now has some online documentation as well.

As a practical matter on 'structure':

1. it is easy to change the content within an existing *.md file, but you have to watch out if you change the content of headings/subheadings, because there are hyperlinks within the documentation that depend on the names of those headings and subheadings.
2. it is relatively easy to shuffle the order and change the description of the existing *.md files in the online table of contents (in mkdocs.yml). As an example of that, online I called ChangeLog.md 'Version History' and moved it to the bottom of the deck;
3. it is also relatively easy to add brand new *.md files. As an example of that, I added Glossary.md. Some care has to be given to new file names, for the reasons given in 3. and 4. below. Changing a file name once it is published online as 'Stable' is non-trivial;
4. it is tolerably easy to split one *.md file into two new parts, as long as one of the *.md files keeps the name of the old *.md file. That allows a user of the online documentation to move between the same 'page' for different versions of Stack. That is why the GUIDE.md file is still called GUIDE.md and not (for example) GUIDE_introductory.md; and
5. deleting or renaming an existing *.md file is less easy - it will interfere with how a user of the online documentation moves between the same 'page' for different versions of Stack. It can be done, but I think it should not be done lightly.

[malteneuss]

Hi @mpilgrem, thanks for that quick and extensive reply. My main recommendation is to separate the documentation into separate, small and self-contained units according to https://documentation.divio.com/, each on a separate page, which from my experience the Rust cargo team and many Javascript and Python frameworks aspire too.

The unit of a guide would be a solution to a typical isolated user problem like setting up a project, e.g., mentioning stack new, stack build and stack exec, nothing more, similar to the concise Cargo setup guide. A summary of a Stack installation unit and a Stack project setup unit could be the main, first and only part of a "Getting started" page like Cargo Getting Started. These few instructions could be mindlessly carried out by anyone who is able to use a terminal. Every other more detailed explanation or next steps would be linked to other documentation units. In that regard for the assumable competency of the reader we could aim for a novice programmer that know how to to use a terminal (otherwise Stack wouldn't be used) and roughly knows that you can build or interpret code to run it. So it could be a pre-university student or a teenager at school.

The unit of reference documentation could be a Stack subcommand with all its varieties.

The reasons for separate pages are that it makes it easier for authors to write isolated documentation units, makes it easier to index and find in search engines and reduces the noise for readers, i.e. no unwanted, possibly distracting text above and below. As an extreme example, the huge single page Nix manual is currently being separated and adapted for among those reasons.

Regardless of what comes out here, it would be good to add your vision and structure remarks to the contributing guide.

[mpilgrem]

@malteneuss, I have made some immediate, interim, changes in response to our conversation above, namely:

• I've added material on Stack's documentation to CONTRIBUTING.md.
• I've used the levels in the online navigation menu to distinguish 'General guidance' and 'Specific topics' under Stack's tool documentation.
• I've changed the top level descriptions in Stack's online navigation: 'Home' has become 'Welcome!', 'Tool documentation' has become 'How to get & use Stack', 'Advanced documentation' has become 'How Stack works (advanced)', and 'Project documentation' has become 'Stack's code (advanced)'. I hope the revised descriptions communicate better what is under the heading.

A browser refresh (F5 key) may be needed on each page to see the effect of the changes to online documentation.

[mpilgrem]

@malteneuss, you and I are on the same page when it comes to 'units of documentation'. The problem is a practical one. The online documentation is currently in 'State A', which is structured, but could be better structured. We can imagine the documentation being in 'State B', which is better structured and which also has different or more documentation. Getting from State A to State B is a huge task. Any intermediate state, which is part-State A and part-State B is much worse state of affairs than either State A or State B because it is neither fish nor fowl. There is risk that if any one person sets off on a journey towards State B, they will never reach their destination. So my own energies have been directed at improving State A, which is something that can be done 'incrementally' and with immediate incremental gains.

In terms of current 'units of documentation', they are distributed and take different forms. For example, stack clean and stack purge are introduced in the 'introductory' guide in a 'tutorial tone of voice'. In principle, they could be described again in the 'advanced' guide in a 'reference tone of voice' - but that would be largely duplicative, and my own energies have prioritised (overall) 'completeness' first. I did have on my back burner a desire to make the 'advanced' guide a complete 'reference'.

As another example, stack dot is currently dealt with as one the specific topics - 'Dependency visusalization' - and that is written in a 'tutorial tone of voice'. It also features in the 'advanced' guide, but that is largely a pointer to the specific topic.

As a final example, stack build is a huge command. Its simple use is introduced in the 'introductory' guide. Its complex use is dealt with as a specific topic. It also features in the 'advanced' guide, but that is largely a pointer to the simple introduction and the specific topic. The challange with stack build is not to drown out the 'signal' of its simple use with the 'noise' of its complete description.

[malteneuss]

@mpilgrem Ah nice. That small renaming of titles helps a lot in navigating the documentation topics.

I see your point with an intermediate refactoring state being worse. If according to your current documentation priorities State B is not worth the effort and risk, at least not for now, then that's fine with me.

[smichel17]

As I noted in #5457 (comment), I think an intermediary step that would be an improvement over 'State A' would be the addition of "Reference material" which simply catalogs the effects of each of the stack commands/flags.

This would ease the pressure on the Guide to contain All information, since it could link to the reference docs where appropriate. Optimistically, it might even allow the Guide to be improved, by trimming extraneous information that currently has no other place to go.

The trade-off: there will be some duplicate information, so it will be a little more effort to maintain.

[mpilgrem]

@smichel17, I have restructured the documentation in the master branch (https://docs.haskellstack.org/en/latest/) to give each Stack command its own page, and provide pages for the environment variables that affect Stack and Stack's global flags and options. Those pages, together with Stack's YAML configuration, are grouped together under 'Reference (advanced)'. I have tweaked the content of some existing pages to give them more of a 'reference' style. There is more to be done to conform the editorial style across pages, but I think it provides a foundation to build upon.

[mpilgrem]

I am closing this issue as a lot has happened to the online documentation since it was opened and to encourge fresh issues in the context of the current state of the documentation.