July 29, 2018, 11:30 a.m.

Writing Effective Documentation for Your Open Source Projects

Tiffany W. Developer Newsletter

I am just beginning to write documentation for my open source projects. I have had some stumbles along the way but I am still learning how to communicate what each app/tool does.

Here are some of the basics that I am learning while drafting my docs:

  1. Have a good Description and Getting Started sections to get a user up to speed on installing the tool/s on their local machine for testing and development.
  2. Make sure you outline the dependencies for the project. Do you need to install node or another tool? Let the user know in the Dependencies section.
  3. Make sure you break your Installation section down to be as clear as possible. Be concise; let the user know how to install the tool/s step by step. Brevity where it needs to be and more elaboration if something is complicated.
  4. If it is a large open source project, having a Testing section should be something you consider. Let the user know what test suite you are using and how to run the tests.
  5. And finally, add a Deployment section to help your user get up in running in a production environment.

Styles and Themes

If you want a singular place for your documentation, blog about the project, and other materials, think about using a theme and hosting it on a service like Now, Netlify,or Surge.sh.

Picking a static site generator is the hardest part. There are a lot to choose from however whatever you choose should make getting markdown in and out of it relatively easy and the build time should be fast. I am using Docusaurus by Facebook.

I have my docs set up on Netlify and you can find them here and here.

Interesting Tweets This Week

Dan
@dan_abramov

Peak Windows programming was installing a wizard that helps create installation wizards


July 29, 2018, 2:37 a.m.
Kent C. Dodds
@kentcdodds

Coming to JavaScript soon!

https://twitter.com/joelquen/status/1022848078683033601
July 27, 2018, 3:45 p.m.
Tae’lur Alexis
@TaelurAlexis

It happened. Today I was offered a Front-End Developer role and I will be relocating to Seattle. Words can’t even express how I feel. I turned the pain that I felt losing my father into motivation. All of the doubts, the effort that I put in, I can now say I am an engineer. Wow.


July 18, 2018, 10 p.m.

Wrapping This Up

It’s been a good couple of weeks here in Central PA, at least for me. Will have more news as it comes.

P.S. If you like what I am doing here, be sure to  subscribe, follow me on Twitter, buy me a coffee, a book, or support me on Buy Me a Coffee and share the love. You can also subscribe to this newsletter’s rss feed or you can ask me anything.


👋🏾 Hi. I’m Tiffany White. I am a front-end engineer and egghead.io instructor. I sometimes contribute to open source, and blog about web development at Tiffany R. White Blog. I love JavaScript, React ⚛️, and herding cats 🐾 🐈

You just read issue #9 of Tiffany W. Developer Newsletter. You can also browse the full archives of this newsletter.

Share on LinkedIn
Brought to you by Buttondown, the easiest way to start and grow your newsletter.