Technical Document Re-working Group/Resources
Overview edit
This page provides a list of ideas and links to sources about various aspects of technical documentation.
What is Technical Writing edit
Creating a technical documentation plan/strategy edit
- Gives shape to your project
- Purpose -- For what reason are you documenting this thing
- Deliverables -- The documents you plan to deliver
- Requirements (including regulatory if applicable)-- High level needs that the documentation should meet
- Audience -- Who is this for? Envision this as a real group.
- Include a last modified date on documentation (and description of changes when possible)
Evaluating technical documentation and measuring success edit
Requirements edit
Understanding APIs and how they work edit
Simple API Documentation Template and Examples edit
- https://bocoup.com/blog/documenting-your-api
- http://www.klariti.com/technical-writing/2016/11/09/examples-of-rest-api-documentation/
- https://alistapart.com/article/ten-extras-for-great-api-documentation
- https://alistapart.com/article/the-ten-essentials-for-good-api-documentation
- https://gist.github.com/iros/3426278
Documentation writing edit
- http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
- http://www.writethedocs.org/guide/
- http://www.writethedocs.org/guide/writing/docs-principles/
- http://cyborginstitute.org/projects/administration/documentation/
- https://jacobian.org/writing/what-to-write/
- https://jacobian.org/writing/technical-style/
- https://www.divio.com/en/blog/documentation/
Documentation Tools edit
- Comparison of automatic documentation generators: https://en.wikipedia.org/wiki/Comparison_of_documentation_generators
- Confluence Documentation: https://support.atlassian.com/confluence/
Examples of good work edit
- https://alistapart.com/about/style-guide
- https://github.com/PharkMillups/beautiful-docs
- https://docs.python-guide.org/en/latest/index.html
- https://developer.mozilla.org/en-US/
- https://www.twilio.com/docs/guides/how-to-confirm-delivery-in-php -- Check the 3-column scrolling (in wide windows)! Then check the outdated-styling (fuzzy text) in the examples here: https://www.twilio.com/docs/tutorials/account-verification-php-laravel
- https://guides.github.com/
- https://docs.ghost.org/docs
- https://www.latex-project.org/help/documentation/
- https://wiki.archlinux.org/
- https://wiki.blender.org/index.php/Main_Page
- https://codex.wordpress.org/Main_Page
- https://yuilibrary.com/yui/docs/guides/
- https://docs.djangoproject.com/en/1.11/
- https://guides.rubyonrails.org/
- https://help.showpad.com/hc/en-us/articles/212552325-Prepare-content-sharing-for-your-users "I like the way it starts with a "why should I care", then a large visual, then a quick usage section, then a detailed step-by-step usage. I could also imagine dding a then technical usage section."
- https://gohugo.io/contribute/documentation/ (meta) and https://gohugo.io/documentation/ (actual docs)
- https://stripe.com/docs/api and to a lesser extent https://stripe.com/docs
- https://laravel.com/docs/6.x
Analysis of our docs edit
Additional links edit
- https://wiki.documentfoundation.org/images/5/5d/LibO-style-guide.pdf (LibreOffice)
- https://www.mediawiki.org/wiki/Developer_Wishlist/2017/Documentation
- https://en.wikibooks.org/wiki/Professional_and_Technical_Writing
- http://cyborginstitute.org/projects/administration/documentation/
- https://whatcanidoforwikimediacommons.org/
- https://blog.wikimedia.org/2018/02/23/improving-mediawiki-documentation/
- https://www.atlassian.com/blog/add-ons/5-real-life-examples-beautiful-technical-documentation
- https://idratherbewriting.com/
- Someone wrote: my favorite tech tutorial style remains DigitalOcean's "how to X on Y platform" content mill. e.g. https://www.digitalocean.com/community/tutorials/how-to-install-linux-apache-mysql-php-lamp-stack-ubuntu-18-04 (more at https://www.digitalocean.com/community/tutorials )
- https://mwparserfromhell.readthedocs.io/en/latest/
- https://docs.readthedocs.io/en/latest/
- I like the graphics here (slideshow), a mix of documentation page and in-use-screenshot. https://www.infoworld.com/article/3227920/cloud-computing/bossie-awards-2017-the-best-cloud-computing-software.html
- https://meta.wikimedia.org/wiki/Research:Project_documentation_best_practices
- https://phabricator.wikimedia.org/T126500 ("Organize a MediaWiki Documentation Day")
- https://www.mediawiki.org/wiki/MediaWiki_Documentation_Day_2017
- https://www.mediawiki.org/wiki/Wikimedia_Hackathon_2017/Program#Volunteer_During_the_Hackathon
- http://www.writethedocs.org/conf/na/2017/schedule/
- http://www.writethedocs.org/conf/na/2017/writing-day/
- http://opentranscripts.org/transcript/programming-forgetting-new-hacker-ethic/
- https://meta.wikimedia.org/wiki/Technical_Collaboration/Onboarding_New_Developers
- https://www.mediawiki.org/wiki/Technical_Collaboration_Guidance/Index