last letter cap i
https://github.com/jamesstoneco/docsthursday
inspired by Carolyn Stransky talk
note: User Experience the Contributor Experience Second
The same techniques apply for internal API docs, a public commercial product, or a side project of yours
Paraphrased from Ben Hall, The Art of Documentation
- Your own open source project
- An open source project of a buddy
- A project that you love but could use some love
- A hobby or personal interest based project
- One of the public Futurice projects on github
- One from our list of projects that could use some love
- Github Readme
- Github Wiki (optional MVP)
- Static Site Generator
source: Beyond the Readme, Rand McKinney
A good readme is table stakes
– Rand McKinney
source: Beyond the Readme, Rand McKinney
The readme is equally as important as a products home page
–Ben Hall, The Art of Documentation
source: The Art of Documentation, Ben Hall
- Will come confused
- Try to understand what problem it solves
- Want to quickly experiment with it
- Question: how do you show them the value
source: The Art of Documentation, Ben Hall
- 17% forget to include project name
- 31% don't describe the project
- 46% missing project location
- Way too much information, but the wrong kind
source: Readable Readme, Daniel Beck
- Identify the project
- Evaluate
- Use the project (once)
- Engage with the project
source: Readable Readme, Daniel Beck
^ Missing information ^ or no alt tag on image with project name - doesn't count ^ how does the readme make you feel
- Getting Started Tutorial
- Installation
- Summary (why use this, what problem does it solve?)
- Related resources
- Link to Contributors & License file (choose a license)
- List of Maitainers, Core Team, Contributors
source: loosely based on material from Beyond the Readme, Rand McKinney
They can be lovely touches of thoughtfulness in the design, but also things like the language the product uses and the personality it has.
source: https://uxplanet.org/getting-real-about-delightful-design-24af65ebbe93
- Find a project
- Find a starting point
- #writethedocs
Beyond the README: Creating Effective Documentation for Your Project by Rand McKinney, IBM 21m video
With 25 years of experience writting developer documentation, McKinney provides motivation, strategies, and practical applications for writting developer documentation. He introduces the 2 audiences for developer documentation: contributors and users with an emphasis on the latter.
Altough this might be a bit to verbose for starter documenation, as it perhaps focuses on contributors, it has some great advice about what should be in a readme file and how it should be formatted.
A Look Into Static Site Generators For Open Source Docs by Carolyn Stransky 24m video
A review of 46 polled open source projects, from small home-grown to very large projects. Some key takeaways are most projects are concerned with conributor experinence, the community of the static site gen, and automation. Interesting was that language was not a preference but rather having a less steep learning curve was key. Most projects interviewed cited that they were happiest when using a variety of tools that fit their specific needs.
The Art of Documentation and Readme.md for Open Source Projects - Ben Hall 35m video
TODO: write summary
Podcasts, Confrences, Slack Community of Techinical Writers. A huge amount of resources.
How to build a website with github. _How to build a website with github, video 1h28m - video
If you are not a developer, this provides a good walkthrough for setting up github pages / jekyll. Video and demo are targeted towards Technical Writers at the Write The Docs conference.
Write the Readable README by Daniel D. Beck 23m video
In this video Beck did a survey of over 200 public opensource readme files from projects with over 10k stars on github, projects he was familair with, and some closed source readmes. Bias is towards established popular products.
README Checklist by Daniel D. Beck
A series of the 4 ways to build confidence in your users from a readme, described in the talk Write the Readible Readme, that you can easily go through to evaluate your current readme and where it could use some love.
Created by the Facebook Opensource Team to create a simple way to document projects.
Generates a Table Of Contents for markdown files automagically. Important flag: --github
A tool that will automatically add all of the contributors from a file to your project readme file.
Great project for documenting react projects with mdx. Also a great example of good documentation.
A free but add supported way to automatically build and host your docs. You can use standard markdown files in a docs directory and you will need to use python to configure initilaly.