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]http://www.stc-psc.org/what-is-technical-writing/
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]- https://easydita.com/infographic-measuring-the-value-of-technical-communication/#comments
- http://docsbydesign.com/2017/08/06/measuring-the-value-of-technical-writing/
Requirements
[edit]- 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
[edit]- https://medium.com/@coopTilleuls/understanding-apis-b7de5a60248
- https://idratherbewriting.com/learnapidoc/
- https://apithedocs.org
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]- 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
[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