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:
- 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.
- Make sure you outline the dependencies for the project. Do you need to install
nodeor another tool? Let the user know in the Dependencies section. - 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.
- 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.
- 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
Peak Windows programming was installing a wizard that helps create installation wizards
Coming to JavaScript soon!
https://twitter.com/joelquen/status/1022848078683033601
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.
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 🐾 🐈