On 15/12/12 14:46, Jan Stolarek wrote:
OK, so how can we improve it? First of all I think that materials in the wiki are well organized for people who already have some knowledge and only need to learn about particular things they don't yet know. In this case I think it is fine to have wiki pages connected between one another so they form cycles and don't have a particular ordering.
However as a beginner I'd expect that pages are ordered in a linear way (sorry for repeating myself, but I think this is important), that every concept is explained in only one place and that there are no links in the text (even at the end - if the text is structured lineary than I don't need to decide what to read next, I just go to next section/chapter). This is of course a perfect situation that seems to be achievable in a book, but probably not in a wiki (wikibook could be a middle ground?).
Right now there are two pages (I know of...) that instruct how to get the sources: http://hackage.haskell.org/trac/ghc/wiki/Building/GettingTheSources http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions/Git
So the first page here tells you how to get a single source tree so that you can build it. The second page tells you how to create a 2-tree setup for use with GHC's validate; the latter is aimed at people doing lots of GHC development (which is why it's under WorkingConventions). Both scenarios are important, and I think it's more important to deal with the simple case first which is why it is right near the start of the Building Guide. Does that help? Is there something we could add somewhere that would make it clearer?
It seems that many informations in the wiki are duplicated. There are two pages about repositories: http://hackage.haskell.org/trac/ghc/wiki/Repositories http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions/Repositories (after reading the first one source tree started to make much more sense - this is one of the informations *I* would like to get first).
The first page lists the repositories and where the upstreams and mirrors are. The second page contains the conventions for working on other repositories (which is why it's under WorkingConventions).
In general I think that for beginers it would be good if the wiki had a form of a book divided into chapters. I only wonder if it is possible to adjust the wiki for the newbies and at the same time keep it useful for more experienced developers.
The nice thing about a wiki is that you don't have to move content around, you can just make new contents pages that contain whatever organisation you want. So maybe what you want is a separate page that links to things to read in a particular order? Cheers, Simon