1. 3

    The Implementation of Functional Programming Languages by SPJ is good

    Lambda The Ultimate has a good list of papers on language design that are pretty fundamental.

    1. 1

      Thank you!

    1. 2

      Category Theory for Programmers by Bartosz Milewski in blog post form in pdf form in print-on-demand form

      I’m working through this now. Very in-depth but still very approachable. There are a number of YouTube videos by the author covering the same topics, so there’s a deep and diverse reference body if something is a sticking point.

      1. 2

        Thanks! This looks to be very thorough.

      1. 7

        I’d say fundamental papers would be:

        Then building up on top of that:

        1. 2

          Ooooh, thanks! This should have me covered for the season :)

        1. 3

          If you’re interested in the theoretical fundamentals of functional programming, you probably want to start with the Lambda Calculus. This introduction by Henk Barendregt should be a good start.

          1. 2

            Thank you! It seems a bit intimidating at first brush, but I’ll give it a shot.

            1. 3

              Yeah, these papers tend to be a bit heavy on the terse syntax. But this is true for any paper in the field, so getting used to notations like this is a good idea. Just don’t expect to read it at the same pace as you would read regular prose. Take your time to truly understand the notation before continuing and it will actually make quite a bit of sense.

              If you want something simpler to begin with, you might want to try The Little Schemer first. This is the book that made the concept of recursion “click” for me. It starts out absurdly simple but it ends with you implementing the Y combinator (which is a “pattern” in lambda calculus). The nice thing about it is that it requires no more than basic high school knowledge but it goes surprisingly deep.

            1. 3

              Thank you, Graham! These look very good. BTW I just got your book yesterday, looking forward to reading it :-)

              1. 2

                Thank you, I hope you enjoy it! Please do send me a message with your questions and feedback :)

            1. 3

              I liked this article very much: the points it was making, the writing style, and the art direction. Thanks for sharing!

              1. 2

                I mean it’s pretty good, but it’s missing color quaternions.

                1. 1

                  Thanks! I have not heard of color quaternions but I would appreciate a reference to get the feel of them!

                  1. 1

                    Based on the italics and that quaternions have been a topic of discussion lately, I think that was a joke.

                    1. 1

                      I knew it! Taking a stab at my math insecurities, I see :)

                      1. 2

                        LOL! I was joking. Color quaternions are a real thing, but I doubt they would be actually useful here. The gist is that quaternions are a set of related imaginary numbers that loosely map to rotation in 3d space. Rotation in 3d space can be thought of as rotation in a color space. Quaternions are nice when you’re composing many changes, an example might be shifting every color in a color pallet. Color quaternions are used mostly in image processing algorithms (and even then pretty rare) but I’ve honestly never seen them for a color library and I can’t say that they’d actually be useful in any meaningful way. Being said you should be able to take any existing quaternion library and just map any colorspace to it if you wanted to fulfill the joke.

                        academic Explorations in Quaternion Color.pdf

                        related GDI+ Rotating Colors

                        1. 1

                          Haha, thanks! It actually sounds pretty interesting, if abstruse.

                          1. 1

                            color rotations are pretty neat though and would be less of a pain :P.

                1. 3

                  Culori does not have a Color class. Instead, it uses plain objects to represent colors

                  I like this already!

                  The variety of distance metrics looks promising. Starred, will check out next time I do color comparing!

                  1. 1

                    Thanks! I initially started out with a fluent API, but I felt it complicates the API unnecessarily and I wanted to make it easy to add additional color spaces, with a set of basic functions that work across the board.

                    In regards to the distance metrics, I’ve tried to work from primary sources, and I think I got the formulas right, but for some of them I couldn’t find reliable test data. However, empirically they seem to work well: https://beta.observablehq.com/@danburzo/nearest-css-named-colors

                  1. 3

                    Buried in a footnote is a video from Strange Loop 2017 which may be of interest (I haven’t watched it yet): https://www.youtube.com/watch?v=5R9eywArFTE

                    1. 2

                      I did a bit of research on this for Pikelet, and I think I’m going to go with http://docusaurus.io/ for this, in a docs/ directory in the Pikelet repo. At the moment I’m using mdbook, but it’s not as flexible/full-featured as I’d like. Docusaurus offers versioning support, for instance.

                      1. 1

                        I’m a bit uncomfortable with React-powered front-ends at the moment. I’ve looked, however, at Hugo and Eleventy. Hugo is crazy fast, but I’m Go-illiterate so I have little chance of extending it in case it’s needed. Eleventy is, for its principles, very close to my heart, but I haven’t had the chance to try it out yet. (I had something similar to it in the works), but I’m not sure when I’ll be able to pick it up again.

                        1. 1

                          Docusaurus and Vuepress, etc. are server side rendered, so you don’t pay the overhead on the browser front. The advantage is that you get to hook into other front end tooling like KaTeX that is harder if going with a non-front-end language. This was one of the main issues I had when looking into Rust solutions (and if I’m honest, I’d rather be writing JS/Typescript than suffer writing Go). Also, if you do eventually need dynamic content, having React on hand is a big plus. Curious to know why you are uncomfortable with it :)

                          1. 1

                            I don’t know exactly, it’s kind of inexplicable because I otherwise love React :-) I guess it’s skepticism/reluctance about batteries-included generators which throw every feature at you at once; not that this applies to Docusaurus specifically, but I think my first interaction with Gatsby — with its GraphQL and what-not — kind of solidified this position.

                      1. 6

                        I kind of doubt anyone will read this, but hey here I go.

                        There are different sets of documentation, that go in different places.

                        1. Getting up and startedreadme.md
                          The read me will probably be the first and most often seen piece of your project. This is your sales pitch, this should be a short as possible while including the information required to get up and running.
                          • Notices (e.g. this is being deprecated, major version release happening Oct 31th 2018, etc).
                          • What is this and why should you care.
                          • How to install
                          • How to access
                          • Where to find stuff
                        2. Documentation for classes, methods, etc. → whatever the language specific norm is.
                          Commonly this goes into /doc (eg Yard). That being, for languages like Rust or Java I actually prefer the inline documentation. This is often meant for the developers not the consumers.
                        3. “I’m trying to do X, how do I?” type questions. → GH Wiki
                          Gives a globally accessible page to link to. Also allows for a much less structured way.
                        4. Release Notes.Changelog.md
                          See Olivier Lacan’s KeepAChangelog.com
                        5. Other stuff. → on root if possible
                          This is the stuff mentioned in the last point in 1. Stuff like CODE_OF_CONDUCT.md & CONTRIBUTING.md
                        1. 2

                          hey, I read it! :-) I agree with almost everything, except my reluctance re: the GitHub wiki, which seems to me is hard to open up to contributors.

                          1. 1

                            That’s actually a really good point, which I don’t have a good answer to.

                            You could to a GH pages style resource & reference it in the README file. Aside from that I can’t think of any particularly good solution.

                        1. 2

                          I’m not saying it’s necessarily the best way, but for my Dasynq library I wrote the documentation in HTML, and included it in a doc folder (https://github.com/davmac314/dasynq/tree/master/doc/html). The disadvantage is that you can’t easily read it on Github, but I solved this by also hosting it elsewhere (http://davmac.org/projects/dasynq/doc/) and linking that from the README - though there are also ways to view HTML hosted in Github (https://htmlpreview.github.io/?https://github.com/davmac314/dasynq/blob/master/doc/html/index.html).

                          The main advantage of bundling the documentation this way is that it can be read offline. I guess that’s becoming increasingly irrelevant - but I personally still do a lot of programming on a train where reception is sketchy.

                          (And of course there’s no need to write in raw HTML as I did - you can write in docbook or markdown and use a converter to produce HTML).

                          Edit: I should also mention that I also include a much briefer version of the documentation as markdown: https://github.com/davmac314/dasynq/blob/master/doc/USAGE.md

                            1. 1

                              Yes, there are various “tricks” to use GitHub capabilities, depending on how crazy you want to get. For example, you can have your markdown files in a /docs folder, then generate a static site that you then publish on the gh-pages branch using a npm package called, appropriately, gh-pages.

                          1. 1

                            Addendum: The purpose of my question is two-fold. For one, as I’m preparing to finish the first release of https://github.com/evercoder/culori, I want to see what good documentation looks like for people; as an end-user (usability, portability, etc.) and as an author (maintainability, ergonomics). And the second reason is I’m documenting my forays into open-source, and I want to write these things down, as a guide to myself and others.

                            1. 1

                              There are many places where one could store a project’s documentation

                              You’re far too optimistic if you really assume the people actually do documentation properly unless they are forced to do, or get paid for it :)

                              1. 1

                                Yeah… Although for open-source projects (at least of the JavaScript flavor) there are quite a few examples of excellent documentation. I’m mostly referring here to the kind of project where you actually want people to use it. :)

                              1. 2

                                A decent thing with the GitHub wiki that some may have missed is that it is also accessible as a separate github repo (i.e. just clone the github.com/author/project.wiki) but one that doesn’t pollute the git history of the main repo with “fixed typo 1234”.

                                1. 2

                                  That’s true. On the other hand, I don’t think Github supports making Pull Requests for the wiki, right? Which is quite important for accepting contributions to the documentation, IMO.

                                  1. 2

                                    Yeah, I think the permission system of github wiki only follows project settings otherwise – but at least its decoupled. Too bad that doesn’t apply to the issue system.

                                1. 7

                                  A thing that has helped me tremendously, I think, was getting into a practice of documentation.

                                  On the one hand, a thing you can start right away is keeping track on the ways you spend your time on a given task — how much of it is research, vs. debugging, vs. trying things out, et cetera. This can give you insight into your day and guide your efforts for improvement.

                                  On the other hand, documenting the things you learn — either along the code as comments, or into separate documents (e.g. “Today I Learned” type of repositories, see this thread for inspiration) — can give you, on the longer term, a wealth of knowledge you can refer back to. It has never ceased to surprise me how easy it is to forget how to do things in a year’s (or even a month’s) time, and I have never regretted documenting anything.

                                  Another super important thing is to ask for help when you get stuck, because that’s when things go sour. Ask for advice, do pair programming, anything that can get you back on track, instead of procrastinating / agonizing about a problem for too long.

                                  1. 2

                                    How does it compare to weasyprint? I’m yet in search for the ideal solution to get HTML e-mail into a printable format without firing up firefox (I use mutt to read my e-mail, and occasionally need to print e-mails), but especially eBay’s automatic e-mails have broken pretty much every HTML renderer other than Firefox or webkit-based ones.

                                    Before you ask why I print eBay e-mails. I’ve needed to sue an unwilling eBay buyer, and German courts will only accept printed documents.

                                    1. 2

                                      I haven’t run it with HTML emails yet, but as long as it looks decent when you visit about:reader?url= in Firefox (and possibly even if it doesn’t), you should be able to get a good PDF out of it. I guess the only advantage of sorts to percollate is that it uses Puppeteer (i.e. headless Chromium), so you should get all the perks of WebKit rendering.

                                      The code itself is pretty basic (most of it is in index.js), so I hope anyone can use it as a starting point to build their own custom stuff by mixing and matching the libraries (jsdom, readability, puppeteer).

                                    1. 4

                                      Have you got any examples of what it produces? Some kind of before-and-after thing? Or am I just missing something?

                                      1. 2

                                        Here is an example output from one of my articles. It basically runs the webpage through Readability and exports it as PDF. It can also collate many web pages into a PDF file (similar to Wikipedia’s Create PDF book functionality).

                                      1. 5

                                        Nodding in agreement throughout the article. I like how it delineates a senior engineer’s work from a manager’s work, a boundary I have struggled with in the past: trying to do both had me overwhelmed / burnt out, but giving up the latter has put me back on track.

                                        1. 1

                                          OK, this sounds very intriguing, if only for being so disconnected to how I/we usually work; and I want to dig into it when I’m fresher, but if someone could ELI5 to after-hours-me, that’d be splendid.

                                          As for PRs, I did find myself longing for better tools to tackle larger Pull Requests than what the GitHub UI has to offer. Mainly “saving progress” somehow, or marking individual files as “read”.

                                          1. 3

                                            As for PRs, I did find myself longing for better tools to tackle larger Pull Requests than what the GitHub UI has to offer. Mainly “saving progress” somehow, or marking individual files as “read”.

                                            There’s a bunch of commercial services that do this, I think https://reviewable.io/ is one. A past client of mine uses Reviewable.