Technical Document Re-working Group/Resources

Overview

This page provides a list of ideas and links to sources about various aspects of technical documentation.

What is Technical Writing

http://www.stc-psc.org/what-is-technical-writing/

Creating a technical documentation plan/strategy

• 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

• https://easydita.com/infographic-measuring-the-value-of-technical-communication/#comments
• http://docsbydesign.com/2017/08/06/measuring-the-value-of-technical-writing/

Requirements

• https://en.wikiversity.org/wiki/Technical_writing_specification
• http://sce2.umkc.edu/BIT/burrise/pl/appendix/Software_Documentation_Templates/

Understanding APIs and how they work

• https://medium.com/@coopTilleuls/understanding-apis-b7de5a60248
• https://idratherbewriting.com/learnapidoc/
• https://apithedocs.org

Simple API Documentation Template and Examples

• 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

• 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

• 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

• 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

• https://www.mediawiki.org/wiki/User:Contraexemplo/Outreachy
• https://www.mediawiki.org/wiki/User:Contraexemplo/Outreachy/Outreach_strategies
• https://www.mediawiki.org/wiki/User:Contraexemplo/Outreachy/Final_report

Additional links

• 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