Pretty glad someone’s updating the guide!

The updated version could be improved by shaping it into clearer sections because we’d like newcomers to feel like it’s light and easy. Layers is a great way to achieve this.

The first time I ran through the task list (not very long ago), it felt light and easy. This was because it was chunked well.

So, my suggestion would be to have a third sentence/paragraph in the introduction section that explains what the overall steps are that we’re going to explain next. Provide links down into those sections, and make it really clear that those sections are sections, if possible.

“Contributing to GHC is a simple process conceptually: it consists of [setting up your build tooling], [finding an issue/feature] for you to work on, [working on the code], then getting it [approved and merged].”

At each section, you could reiterate how to do that driving from the overarching aim of the explanation for the section. (Having an introduction to each section would help here, too).

For example, having a canonical way to determine what a good issue or feature to start on would be awesome, as would having somewhat of a mentor/buddy to help new users when working on their bugs (ie one or two people assigned to a newcomers’ first two or so tickets to help them through any issues until they feel confident). Not sure if our contributors allow for such things yet, tho.

On 27 Feb 2019, at 9:06 pm, Tobias Dammers <tdammers@gmail.com> wrote:

Dear all,

With the migration of our affairs from Trac to GitLab nearing
completion, I would like to ask for a final round of feedback on the new
Newcomers' Guide to GHC development.

The draft can be found here:

https://github.com/tdammers/ghc-wiki/blob/wip/newcomers/newcomers-tutorial.md

TL;DR: If you have any kind of input / critique / praise regarding this
document, feel free to reply, or, even better, issue a PR on github.

Some background:

The purpose of this document is to provide potential contributors with a
practical, no-nonsense tutorial, guiding them from "I know nothing about
GHC development" to their first successful merge request.

The document has been compiled using existing wiki content, revised and
edited to match the current state of affairs (particularly using Hadrian
as the recommended build system), and to tune it to the target audience
of first-time contributors. As such, we avoid going off on tangents
(e.g., we do not explain how to use the make-based alternative build
system), and we only explain what you need to understand in order to get
going (e.g., we do not provide a complete run-down of all hadrian
options).

A few nonlinearities were deemed necessary in order to make the tutorial
suitable across target platforms; Windows in particular requires some
special attention. Other than that, however, we try to provide as linear
an experience as we reasonably can.

So with that said; all feedback and suggestions on this are welcome. We
have gotten some great responses already, but I'd like to gather one
more round of feedback before merging it into the freshly-migrated
Haskell Wiki on GitLab.

Thank you for your attention!

--
Tobias Dammers - tdammers@gmail.com
_______________________________________________
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs