How do you document your projects? Do you keep a programmer’s notebook? As you write code, you will have ideas, notes, code snippets and other things that you have learned. You’ll want to keep code that you didn’t use and save for later. By keeping a programmer’s notebook, you’ll create a personal reference that you can use for other projects and documenting your code for your users.
What tools do you use for writing documentaion?
You can use pen and paper to create a bullet journal or collect your notes and ideas. If you want to use an app, I have collected 4 tools that you can choose from.
Boostnote is a note taking app for programmers. You can take notes and collect code snippets. Boostnote is customizable and usable anywhere. You can write notes on your laptop and share with your mobile devices.
Quiver is a programmer’s notebook. You can mix code, text, Markdown in a note. You can install Quiver on your Mac and iOS devices.
Use Bear Writer to create notes and prose. You can organize your notes any way you can. This app is available on your Mac and iOS devices.
Write the Docs
Write the Docs is an open source community dedicated to creating wonderful documentation. They provide guides on writing great documentation, conferences and meetups. Write the Doc is build using the Sphinx static site generator.
Whether you use pen and paper or an app to document your projects, you’ll have a reference that can help you better understand the problems, solutions and things you have learned. Writing documentation for yourself or your users makes you a better programmer. If you want to write better documentation for yourself and your users, Mark has collected tools and resources for creating great documentation.
What is microcopy? It is the smallest piece of content on your website or app. Microcopy can be text-based or visual. Text-based includes buttons, calls to action, error messages and forms. Visual microcopy focuses on images and videos.
Microcopy needs to be easy to understand, short and draws the user in. It should guide the user and help them to understand how to use your website or app.
What can you do to improve your microcopy?
Talk to your users like a person
Does your copy sound conversational or like a marketer? If it sounds like a marketer, change the words. You want to write copy with the same words that your users use.
Use copy to guide your users
Write short and helpful sentences, not paragraphs. If you need more than 8 words to explain what the users need to do, rewrite it.
Writing a tutorial is a good way of sharing how you solved a programming problem. Programmers use tutorials to learn how to write the code for themselves instead of depending a all ready written code. Tutorials can be a quick way to learn how to do something. What do you need to write a good tutorial?
4 Items to include in a tutorial
Step by step instructions
Version of software or tools
Step by step instructions
By providing step by step instructions, you can break the tasks down into easy and understandable pieces. Your readers will be able to follow what you learned and do it themselves.
Sometimes, steps aren’t enough. You need to show your reader what happens. A screenshot can show you what to expect, look for or do. A good screenshot compliments what you want your reader to do next.
Make your code samples easy to copy and to understand for new and experience programmers. You can use a tool like CodePen.io to include your code. Or use one of these 4 Ways to Add Code Snippets.
Version of Software or tools
Your software and tools change over time. New versions come out. Let your reader know what version of the software that you were using.
Writing a tutorial can help you to understand a new concept or programming problem thoroughly. Use these items to help explain what you have learned. When you teach others, you learn new things about the concept that you are teaching.