Sometimes Dragons

Docs about Tech about Docs: A Quick Take on Docsy

Share via Twitter Share via Facebook Share via Linkedin Share via Reddit

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 commas). While the announcement positions Docsy as a solution specifically for launching open source content, per Docsy’s own README file, it is designed for (and at first glance is appropriate for) “technical documentation sets” more broadly.

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 user guide (built on Docsy) and an example “Goldydocs” site with corresponding example project 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.

Screenshot of the Docsy Goldydocs example site.

The Docsy example “Goldydocs” explains and models how to write docs on Docsy

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’s clean templates and style guidance, I would have been absolutely thrilled. 

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. 

 

Disclaimer: Google is a RedMonk client.

No Comments

Leave a Reply

Your email address will not be published.