I’ve written this guide to publishing Elm packages. I hope that it’s useful for both new and experienced Elm package authors! I welcome your feedback and suggestions.
The purpose of the guide is to provide you with resources to get started writing an Elm package. And to help you write an Elm package that is:
Valuable
Constrained to prevent impossible states
Easy to learn and use
Easy to tell if it’s the right fit for the problem at hand
Consistent with the README and documentation conventions in the Elm community
I was inspired to publish this guide by a discussion in #general of the Elm Slack about how helpful it is to put the design goals of a package front and center. I thought, wouldn’t it be nice to make that a convention in the community somehow. That was the initial impetus, but I also used it as an opportunity to put everything you need to know when you’re working on Elm packages in one place.
what a lovely overview! Thank you for writing this, Dillon! There are so many links and resources here!
Since this is “request feedback”, I do have a few things:
Use Ubiquitous Domain Language
Is this the DDD thing? It’d be neat to define that somewhere. Just a link would be fine. Ubiquitous language is an easy concept to grasp, but I still think it needs to be introduced.
Explicitly State Design Goals in Your README
Here’s the thing: when I’ve observed people getting to grips with a new library, they act like this:
To me, that means that it’s better to emphasize the code first: that smallest meaningful snippet you mention. Figure out exactly the problem your package is solving, solve it, and show how you solved it. That way instead of reading about all the design considerations people can show up, pattern match the thing they’re doing against your API, and know whether to continue. The design decisions are valuable, but they’re not the most valuable thing to someone getting started with your package.
And I’ve actually experienced that impatience myself as a package user when I see lots of words in front of the first example. That’s an excellent point. When it’s set up that way, it can be hard to tell which words you should read if you want the gist of it because the overview statement blurs together with all the details.
Maybe it’s best if packages follow the rule of thumb that newspaper articles do: however far you’ve read, you’ve read the most important content (headline, thesis, opening, details in the case of an article).
So to that end, the order could be something like this:
Yeah! It’d be nice to explictly explain the inverted pyramid style (wikipedia is okay on this topic, but I’m sure you can find better.) I’d say the order would actually be pretty different! Remember that the README is not for the author, it’s for the user. I’d structure it like this:
package title: with the literal names policy, packages are self-descriptive. Wanna do tests? elm-test. Need a date picker? datetimepicker.
extremely short summary: what does this package do? If the package is self-descriptive, what sets this apart from other solutions? If it’s not, what does it do?
elm-test: “Write unit and fuzz tests for your Elm code, in Elm.”
style-elements: “Creates styles that don’t mysteriously break!”
getting started: I think elm-test is a great example of this. If you can make something similar you’re doing fine. Here’s the gist:
code sample with usage: show how your library solves the problem you’re designing against. This is not just for beginners! I go look at READMEs for libraries I’ve used for a while all the time. I need reminders of how things are supposed to fit together because I have a mind like a sieve.
things you need to know to use the library at all: for elm-test, this is “how do I run tests”
things you need to know to use the library well: AKA advanced usage tips
faq: not just a bucket for questions; this should also have some information about the state of the library. Is it maintained? Do you expect the API to change in the future? Answer the things you know people have from your research into making a valuable package.
contributing: This is where you put your design goals, and ask people to open issues before making PRs.
I’ll be a little blunt here: new contributors will not read this, and there’s nothing you can do about it. You’ll still get PRs which violate the design goals, regardless of how well this is written or how many big flashy warnings you have about opening issues first. Just be OK with it, and have this available to link to for clarity.
It’d probably be good to say something like this in your guide! It’s already a wonderful explanation that sets new maintainers up for success, and this is a common frustration that folks will run into if their package sees any measure of success.
I also made the wording about the template less prescriptive and added some notes about packages to look at for inspiration. I’m realizing that there are a lot of ways to effectively convey the key points effectively in package docs, so I’m thinking maybe the template can be a helpful starting point, but just one possible way to do structure your docs.
I’ll be a little blunt here: new contributors will not read this, and there’s nothing you can do about it. You’ll still get PRs which violate the design goals, regardless of how well this is written or how many big flashy warnings you have about opening issues first. Just be OK with it, and have this available to link to for clarity.
I completely agree with this, and I think as you say linking to it in discussions to help frame the conversation is really the most important thing, not necessarily that contributors perfectly follow it on the first try.
contributing: This is where you put your design goals, and ask people to open issues before making PRs.
I think I’m still partial to having a very concise set of design goals near the top to help users see if that vision fits with the problem they are trying to solve. For example, I think that the design goals section in dillonkearns/elm-graphql has helped differentiate between other GraphQL packages in the ecosystem so users know whether to look at other packages or try this one out. I’m not sure it would be as clear to users if it was in the contributing section.
Otherwise I totally agree with your points in the contributors section! I’ll add some details on that as well.
Thanks again for your input! I really appreciate it.
