Hi, 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. Nice effort so far! Julian > On 27 Feb 2019, at 9:06 pm, Tobias Dammers <[email protected]> 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 - [email protected] > _______________________________________________ > ghc-devs mailing list > [email protected] > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
_______________________________________________ ghc-devs mailing list [email protected] http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
