Okay, I've written a draft Haddock-GSOC application: would any of you like to review it / suggest how it could be improved? (or should I just submit it to Google?) I'm particularly wondering whether my proposed time-line seems realistic. -Isaac * What is the goal of the project you propose to do? To improve Haddock, the Haskell documentation tool, both substantively in the short term and to be better factored in the long term. * Can you give some more detailed design of what precisely you intend to achieve? Resolve many Haddock Trac tickets. Specific projects: Make cross-package documentation work; and refactor the comment-parsing out of GHC and into the Haddock code-base. * What deliverables do you think are reasonable targets? Can you outline an approximate schedule of milestones? In the first week I will get Haddock and GHC compilation and patch-making set up, fix some minor bugs and send/apply the fixes. Next I will start to determine and converse about the implementation difficulties with making Haddock work across packages. At the same time, I'll continue working on more minor bugs/features (increasing my familiarity with the code and with the coding process). By the end of June I hope to get cross-module docs working. [Is this a realistic goal?] By this time, I'll have some familiarity with the parsing code (having fixed some of its bugs/infelicities), and I can confront the problem of how to refactor the comment-parsing out of GHC. I can imagine I might only be able to find a partial solution easily, but I'll do whatever I have time for. Optimistic timeline to finish this by the end of July; if I get ahead of schedule, I'm sure I'll know enough about Haddock's infelicities by then to know other mini-projects that would be worth doing. For example, I could improve the layout of the index page Haddock generates (Python docs do it better, for reference, according to http://trac.haskell.org/haddock/ticket/70.) Due to the process of testing my changes, I might even write some documentation, if I see an atrociously documented function in some library :-) * In what ways will this project benefit the wider Haskell community? Better documentation (documentation that is less difficult to successfully write) makes everything flow more smoothly in source-code-land. Especially core (even Haskell-98) library documentation has broken multiple times due to Haddock deficiency, and other library authors suffer from everything from `type` annotations not working, to Haddock-2 parsing being more strict, to... every possible issue, really. The cross-package documentation failure specifically makes people reluctant to refactoring into smaller packages, even when that would increase code re-use. Making Haddock/GHC more composable should make it easier for everyone to make small improvements to Haddock, without delving into GHC as much. Perhaps it might even make possible some new tool different from Haddock that looks at information in comments, should someone desire such a thing. * What relevant experience do you have? e.g. Have you coded anything in Haskell? Have you contributed to any other open source software? Been studying advanced courses in a related topic? I substantially improved Spiderweb Software's scenario-editor for Blades of Avernum (once they made it open-source), adding 3D support and other improvements. (C programming language). I worked on Battle for Wesnoth scenarios some, and I hacked on the C++ code for lexing/parsing their markup language, and I learned my lesson when I failed to coordinate successfully with the development team. :-) They used Doxygen to document their code, though it was not used nearly as thoroughly (at least, not back a few years ago) as a lot of Haskell code is documented today. I hacked on GHC, and this code has been committed: I improved the parsing of negative unboxed literals, and I refactored several places in the code that used language extensions unnecessarily. Also I've contributed to discussions on Haskell development mailing-lists over the years (leading to at least one bug-fix), and reported several more bugs in Trac as I ran into them while hacking in Haskell. I took an advanced-level Artificial Intelligence class in which I programmed in Haskell and got an A. I've read many research papers related to Haskell or compilation. I've used Darcs; I've used Linux and followed its open-source coordination travails for four years now (formerly I used Mac OS). I know (X)HTML and CSS well enough to write my own W3C-validated webpage (and my parents work in web-design so I hear a lot about it), so I should be able to work on Haddock's HTML-generating code easily. * In what ways do you envisage interacting with the wider Haskell community during your project? e.g. How would you seek help on something your mentor wasn't able to deal with? How will you get others interested in what you are doing? I'll start a Haskell-related blog that I update at least weekly with what I've been doing, and I'll be on IRC. If there's a problem... probably my mentor will know who to ask anyway, because they're people who are knowledgeable in the Haskell community. Likely mailing lists include glasgow-haskell-users, cvs-ghc, haskell-cafe, libraries; IRC can be good for resolving some difficulties. Sometimes I should just spend more time meditating on / working on the problem myself; sometimes deciding that it's not a priority, and working on something that I do know how to make progress on, is the best step. I'll try and get people excited when I make progress on something really user- visible :-)... but at least half of what I'll be doing is probably not that exciting to most people and doesn't need to be (it'll just make their lives easier in the future). * Why do you think you would be the best person to tackle this project? I've been hacking with Haskell (and other languages) for several years. This specific project aligns with some of my interests (especially, parsing, and easy-to-use documentation). When there's a conflict on what some code should look like, I'm easygoing -- I'll try to look for a perfect solution, but if that's too hard/impossible I look for a compromise, and I think I have a pretty good sense of when to do that (what's likely to be possible, with how much work), from - hacking, myself, and finding some things more time-consuming than I had presumed, and some easier; - listening to Haskell and other mailing-list arguments for years, and occasionally participating; - having a mentor knowledgeable in Haddock/GHC code who can help estimate things for me and with me. I don't mind if I don't get fame and fanfare, but I've learned also that it's best not to work in a dark corner either -- to communicate early and often, when a design decision needs to be made, so that several different people's perspectives (if needed) can be taken into account.