Add high level overview on how the system works / is supposed to work about hadrian HOT 9 CLOSED

Yes, this is certainly for me to write. I will get on to it as soon as I can.

from hadrian.

@snowleopard If you haven't started with this, I'd take this over with the high level documentation overview I'm working on right now. If we need more documentation you could either add ontop of that or write something more detailed? I'll try to document what I learned so far.

from hadrian.

@angerman Yes, please take over. This week is going to be difficult for me in terms of spare coding time.

I will do a revision once you finish; feel free to leave some spots undocumented leaving as many TODO's for me as you like.

from hadrian.

For the /doc part, should we try to use read the docs? stack uses that as well, and I find it quite good to read.

In anywise, if anything specific should be covered, let's try to keep track of that in this ticket.

from hadrian.

@angerman I am not sure why, but I find the stack documentation confusing. It always felt complicated and daunting to me, although it's hard to point out the exact reason. Not sure if readthedocs contributed to this perception.

(Same is true of cabal documentation, by the way. Maybe I'm just confused about the whole package management issue, not stack or cabal specifically.)

Personally, I'd prefer a simple Markdown document for the /doc part in the first instance. Once it starts to outgrow this simple format we may consider other options.

from hadrian.

I dislike the stack stuff too. Markdown is simple and clean on GitHub. I suggest once we outgrow a couple of pages, we simplify the build system - this stuff isn't meant to be rocket science!

from hadrian.

@ndmitchell 👍

from hadrian.

Ohh, readthedocs is just a presentation layer using markdown or reStructuredText, stack's documentation is in their doc folder in markdown as well see https://github.com/commercialhaskell/stack/tree/stable/doc

So it must be either the presentation or the writing :-)

Let's stick with bare /doc for now then.

from hadrian.

A high-level overview of Hadrian can now be found in the Haskell Symposium 2016 paper, which is available here: https://www.staff.ncl.ac.uk/andrey.mokhov/Hadrian.pdf. There is a also a Haskell eXchange 2016 talk: https://skillsmatter.com/skillscasts/8722-meet-hadrian-a-new-build-system-for-ghc.

I've linked the talk and the paper in the project README, so I think we can now close this.

from hadrian.