{"id":109,"date":"2019-07-10T18:21:14","date_gmt":"2019-07-10T22:21:14","guid":{"rendered":"http:\/\/redmonk.com\/kfitzpatrick\/?p=109"},"modified":"2019-08-29T16:45:51","modified_gmt":"2019-08-29T20:45:51","slug":"docs-about-tech-about-docs-a-quick-take-on-docsy","status":"publish","type":"post","link":"https:\/\/redmonk.com\/kfitzpatrick\/2019\/07\/10\/docs-about-tech-about-docs-a-quick-take-on-docsy\/","title":{"rendered":"Docs about Tech about Docs: A Quick Take on Docsy"},"content":{"rendered":"

The first thing I look for when I research a new company, product, or technology is technical documentation. This is no different for a docs-centered project like <\/span>Docsy<\/span><\/a>, which <\/span>Google announced today<\/span><\/a> as a set of templates for <\/span>Hugo<\/span><\/a> (which my tech comm colleagues out in industry tell me they love even more than Oxford commas). While the announcement positions Docsy as a solution specifically for launching open source content, per Docsy\u2019s own <\/span>README file<\/span><\/a>, it is designed for (and at first glance is appropriate for) \u201ctechnical documentation sets\u201d more broadly.<\/span><\/p>\n

There are few things more meta than learning about a documentation technology via documentation that has been created on said technology, and I love that Docsy delivers both a <\/span>user guide<\/span><\/a> (built on Docsy) and an <\/span>example “Goldydocs” site<\/span><\/a> with corresponding <\/span>example project<\/span><\/a> that can be used as a template. As one would hope, the actual documentation practices at play in this meta-documentation experience are just as valuable as the actual tech behind it. The project even goes so far as to model the ideal access path for open source project docs: it uses its own README file to direct users to the guide and example site in language that clearly explains navigation paths and purposes.<\/span><\/p>\n

\"Screenshot<\/p>\n

The Docsy example “Goldydocs” explains and models how to write docs on Docsy<\/span><\/p>\n

While the Docsy user guide and documentation are themselves clean and clear, I suspect the example site and project will prove very useful, especially to open source maintainers who have found themselves tasked with creating tech docs more extensive than a README but who do not have much experience producing technical communication. Quite frankly, as enamored as we tend to be with unique visuals and user experiences, if my former computer science students all had turned out technical documentation that followed Docsy\u2019s clean templates and style guidance, I would have been absolutely thrilled.\u00a0<\/span><\/p>\n

For folks who do work in technical communication, Docsy offers a really nice add to an already beloved open source framework like Hugo, and the example material overtly articulates practices and formatting conventions that many of us sometimes overlook in the race to get tech docs out. The project itself is also an invitation (and for some an introductory pathway) for tech comm folks to help contribute to a project that clearly values documentation and good tech comm practices so highly, and I look forward to seeing what kind of response the project generates.\u00a0<\/span><\/p>\n

 <\/p>\n

Disclaimer<\/b>: Google is a RedMonk client.<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

The first thing I look for when I research a new company, product, or technology is technical documentation. This is no different for a docs-centered project like Docsy, which Google announced today as a set of templates for Hugo (which my tech comm colleagues out in industry tell me they love even more than Oxford<\/p>\n","protected":false},"author":47,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"spay_email":"","footnotes":"","jetpack_publicize_message":"","jetpack_is_tweetstorm":false},"categories":[4],"tags":[],"class_list":["post-109","post","type-post","status-publish","format-standard","hentry","category-tech-comm"],"jetpack_featured_media_url":"","jetpack_publicize_connections":[],"jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/posts\/109","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/users\/47"}],"replies":[{"embeddable":true,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/comments?post=109"}],"version-history":[{"count":0,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/posts\/109\/revisions"}],"wp:attachment":[{"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/media?parent=109"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/categories?post=109"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/redmonk.com\/kfitzpatrick\/wp-json\/wp\/v2\/tags?post=109"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}