Table of Contents generated with DocToc
- Slides
- Resources
- Beyond the README: Creating Effective Documentation for Your Project by Rand McKinney (21m video)
- Loopback Readme Guidelines
- A Look Into Static Site Generators For Open Source Docs by Carolyn Stransky (24m video)
- he Art of Documentation and Readme.md for Open Source Projects - Ben Hall (35m video)
- Write The Docs
- How to build a website with github tutorial link video 1h28m - video
- Write the Readable README by Daniel D. Beck 23m video
- README Checklist by Daniel D. Beck
- Tools
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 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.
TODO: write summary
Podcasts, Confrences, Slack Community of Techinical Writers. A huge amount of resources.
How to build a website with github tutorial link 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.
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.
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.