Note: This section of the site is under heavy construction, tread carefully.
106 bookmarks by garrettc
"Markdoc is a Markdown-based syntax and toolchain for creating custom documentation sites from Stripe."
Bookmarked on • #
"Titbits and curios from the video game mod archives. Curated by Alice O'Connor."
Bookmarked on • #
Bookmarked on • #
Bookmarked on • #
Detailed descriptions, with full methods and attributes, for each of Django's class-based generic views.
Bookmarked on • #
Use readme.so's markdown editor and ready made templates to easily create a simple README for your repositories
Bookmarked on • #
The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.
Bookmarked on • #
"There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four. They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely."
Bookmarked on • #
"The best way to understand Django's class-based views is to see it in Classy CBV, so pick your version and jump in at the deep end."
Bookmarked on • #
Bookmarked on • #
Bookmarked on • #
"This document is for programmers who take one look at activitypub.rocks, click on through to the documentation, and can't make heads or tails of it."
Bookmarked on • #
A super interesting look into how Etsy prevents documentation from going stale by splitting it into “how” docs (prone to change), and “why” docs (less likely to change)
Bookmarked on • #
Get oriented on some basics of Docker before diving into the walkthrough.
Bookmarked on • #
"A how-it-works-style research prototype for understanding a code library."
Bookmarked on • #
Say hello to Kit, a set of tools for developing, documenting, and testing React components.
Bookmarked on • #
Bookmarked on • #
"This document aims to provide readers with a shorter overview of the W3C Process Document written in plain English. The original W3C Process Document is a complete document, written to be legally accurate and give indepth detail on each item and process. This document aims to give an overview of the main document, so new and existing W3C participants can gain an understanding of all W3C processes and know where to go for more information."
Bookmarked on • #
"When we launched our first SoapBox hero I was surprised to discover a document used to introduce her working style to her team. I had never seen that before and it was awesome! Did others have these? I needed to know. Eventually, I found a treasure trove of examples by Engineering Leaders from companies with some of the best culture in tech. They called them Manager READMEs, or Manager User Manuals. And they’ve graciously let me share them with you."
Bookmarked on • #
"For some reason people think that JBGE implies that the artifact isn't very good, when in fact nothing could be further from the truth. When you stop and think about it, if an artifact is JBGE then by definition it is at the most effective point that it could possibly be at."
Bookmarked on • #
If you manage to create amazing API documentation and ensure that developers have a positive experience implementing your API, they will sing the praises of your product. Continuously improving your API documentation is an investment, but it can have a huge impact.
Bookmarked on • #
"Infusion is a high performance generator of rich and accessible documentation sites in the form of progressive web applications (PWAs). That means the documentation sites you create can be saved to your devices and read offline. Because Infusion instances exist as Github repositories, this is possible out of the box. When you commit and push changes to your content, your Github Pages site is updated and a new service worker is installed."
Bookmarked on • #
"There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four. They are: tutorials, how-to guides, discussions and technical reference. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most software documentation - often immensely."
Bookmarked on • #
"Poorly written documentation is like food that tastes bad or that’s hard to eat. The sole purpose of documentation is to be read, so it must be well organized and optimized to be easily read and understood."
Bookmarked on • #
A really really good example of well written docs, super friendly and easy to follow.
Bookmarked on • #
"And this got more complicated when we came with style guides. Or maybe component libraries. Or pattern libraries. Did you hear about design systems? It’s the big thing for 2017. Are they the same? Is there a difference? Why don’t we call it simply documentation?"
Bookmarked on • #
"This is a general design guide for networked APIs. It has been used inside Google since 2014 and is the guide we follow when designing Cloud APIs and other Google APIs. It is shared here to inform outside developers and to make it easier for us all to work together."
Bookmarked on • #
Just because your users don’t ask for help doesn’t mean they don’t need it.
Bookmarked on • #
"Here is a list of links to all the online design system documentation of note I found while researching how other teams document their design systems, brand guidelines and styleguides."
Bookmarked on • #
Patience and empathy are the basis of good documentation, much as they are the basis for being a decent person. Here's a how-to for creating better open source project docs, which can help your users and grow your community.
Bookmarked on • #
"During every project a lot of knowledge is “stored” in team members brains. Unfortunately, human memory is not the safest place to keep valuable information and that’s why you have to secure the project knowledge “on paper” (of course you will use computer for that). In this article I’ll try to give some hints that I’ve found reasonable for the 3 most common types of documents."
Bookmarked on • #
A collection of information about the PagerDuty incident response process. Not only how to prepare new employees for on-call responsibilities, but also how to handle major incidents, both in preparation and after-work.
Bookmarked on • #
Bookmarked on • #
A great internal document from the US Government digital team about how to use Slack.
Bookmarked on • #
Excellent tips and advice for documenting a design system.
Bookmarked on • #
Bookmarked on • #
Get more users and fewer support requests by leveling up your writing and technical documentation.
Bookmarked on • #
A decision tree for adding new patterns to a framework
Bookmarked on • #
Bookmarked on • #
Tutorial on how to produce a high quality screencasts
Bookmarked on • #