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
 * http://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/
 * http://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."

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://whatcanidoforwikimedia.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