Skip to content

Latest commit

 

History

History
152 lines (118 loc) · 9.36 KB

README.md

File metadata and controls

152 lines (118 loc) · 9.36 KB
Raw

logo

project-checklist

A checklist of things to do before releasing your project

The best projects sell themselves

🎨 Initial Presentation

Think of the README as the elevator pitch for your project. Keep it concise and to the point

  • Don't list out all the functionalities of your project as the first thing in the README
    • Recommendations
      • Showing users all the options they can do with something will confuse and/or overwhelm them
      • The first example you show should be the absolute most basic example that is working and copy-and-paste-able.
      • My definition of simplicity: something is simple when there is nothing left to take away from it
      • Don’t initially show users multiple ways of doing something. Show them only one way of doing it. Be careful which way you show them. Choose the way that they will use most of the time
      • It’s tempting to show your users all the things they can do with your project. In many cases, however, this will intimidate users (especially those that are new to the idea or the ecosystem)
  • Start by showing the most common functionalities first. If your project is an API, only initially show examples of the most common APIs that are used. If your project is an app, show screenshots of the pages that are most commonly used
  • Include a live demo. A video is a thousand pictures and a picture is a thousand words
  • Communicate your Value Proposition
  • Provide interactive examples. Having ready and runnable examples lowers the barrier to using and testing out your project
    • Recommendations
      • General Programs: consider using replit to provide live and runnable demos
      • Web Libraries: consider using codesandbox to provide live and runnable demos. For node, consider running them in runkit
      • Web Apps: Provide links to the hosted version of your app

💰 Value Proposition

A value proposition is a promise of value to be delivered, communicated, and acknowledged

Figure out the value your project brings to your users. What does it provide them that they don't have already?

  • Examples

    • React: Declarative, efficient, easy to use
    • Babel: Easy-to-use, pluggable
    • Yarn: Performance, ergonomics, reproducible installs

  • Recommendations

    • A value proposition can have multiple propositions
    • Having better performance than competing projects usually isn't enough to convince people to use your project. If you are using better performance as your only value proposition, consider adding other value propositions (see the tweet).
  • Decide what your value proposition is
  • Communicate your value proposition in your README and in your tagline

💯 Project Quality

High quality projects are much more likely to retain users over time

  • Be your own user. If you’re making a library, build an app that uses it. See what you like and dislike about your library from the perspective of a user
  • Before MVP (minimum viable product), all tests should be passing and docs with examples should be written and made available

👑 Branding

Make your project unique and memorable (most people only focus on technical aspects of a project). While this is important, this should be done close to finishing the MVP of a project

  • Name your project
    • Recommendations
      • Name your project something that is easy to remember
      • Try to make the name related to what you’re making
        • Examples
          • Parcel: “parcel” is the name of a bundler
          • React: “React” comes from reactive programming
          • Flow: “Flow” comes from flow graph inference
      • Single words or combining common words
        • Examples
          • React
          • ”micro-soft“
          • ”face-book“
          • ”web-pack“
      • Don’t worry too much about choosing a name and having a package with that name already taken. If your project becomes more popular than the project that has taken the name already, the owner of the package will usually give you the package name if not too many people are depending on it
  • Add a tagline
    • Recommendations
      • Avoid wordy taglines--they are hard to remember and understand
      • Your tagline should communicate your value proposition
    • Examples
      • React: A declarative, efficient, and flexible JavaScript library for building user interfaces
      • Babel: The compiler for writing next generation JavaScript
      • Yarn: Fast, reliable, and secure dependency management for JavaScript
  • Add a logo
    • Recommendations
      • Make sure your logo is one of the first things your audience sees when they see your project
      • Don’t use letter logos. Use images or icons that are similar to your project. For example, if your project is called joker, add a picture of a joker card instead of simply creating a logo with the word “joker”
      • Easily compress your logo with Squoosh
  • Choose a color theme
    • Examples
      • React’s is blue and light blue
      • Flow’s is yellow and gray
      • Make sure your docs and website follow this color theme
  • Further reading

✈️ Onboarding Methods

Lower the barrier to entry by providing the most “native” ways of onboarding people. Make it as easy as possible for users of competing projects to start using your project.

In general, here's how this works: say you have library y that competes with popular libray x, write documentation for a migration path from library x to y.

  • Examples
    • Figma, a vector graphics editor, gained users by allowing Sketch users to import Sketch files into Figma
    • Laravel onboarded many Rails users by providing terminology and conventions that were similar to Rails

🧹 Code Conventions and Infrastructure

Using standard code conventions and infrastructure lowers the barrier for people that want to contribute to your project. This sometimes translates to more contributors over time because initial contributors sometimes become long term contributors

  • Don’t use meaningless variable names or examples
  • Provide examples that are going to be similar to what users will use your library for
  • If you are making an assertion library, don’t make examples like so:
    • Bad: foo = checkIsUsername(a)
    • Better: username = checkIsUsername(user.username)
  • All examples should be standalone
  • A lot of users copy and paste examples just to see if they can get your project working. Having examples that can be copy and pasted and gotten working will lower the barrier to new users
  • In projects that are too complex to have standalone examples, at the least they can have standalone environments that they can run their examples in. Docker, for example, can be used to implement this well. Users can spin up a docker container and run their examples in the container instead of spending time getting their own environment set up

️📣 Spread the Word

To maintain communication with existing users, use a newsletter. Consider using mailchimp for this.

🤑 Funding

Optional

  • Mention Related Projects
    • Listing projects that are related to your projects can help users with discovering other related projects
    • This is mostly for the purpose of spreading awareness and improving the connectedness of the community
    • For each project you list, provide the name of the project and a short description of it
    • Examples