I've worked on plenty of projects that required design documentation. I found this to usually add little value, as the design documented change significantly during development, though it rarely gets updated, and it's easier to just scaffold templates in Sitecore than to create a work document that details what fields you are planning to create.
That thought left me thinking there should be a better way. Sitecore is a content management system. All the details of the design of a component are just meta data that Sitecore is already tracking, so should there be a way to generate documentation based on the templates, items and meta data already in Sitecore?
Last weekend, I built such a feature, adding Feature.Doc to Sitecore Foundation. Currently only in the SxA branch, it has an extra template for documenting SxA features that can be ommitted if not working with SxA pretty easily.
The feature itself is pretty easy to use.
- Use the Documentation Folder Template to create an organizational structure for your documentation.
- Add a Feature Document to one of the folders.
- Specify what makes up the feature by filling out the fields to specify what templates, branches, renderings, placeholders and more that you want to document.
- Note you can also list the fully qualified class (including assemblies) if you want to document .Net Classes as well. This even grabs xDoc comments if you use them and output Xml files to the bin directory.
- Preview the Feature Item. A complete design document including a table of content are rendered.
- Print to PDF as the CSS for the document includes things like printed page breaks to make it render cleanl
Note that this also encourages you to add help text to your templates and renderings as those will be outputted as descriptions in the design document.
Feel free to extend this Feature to customize the doucmentation. Each section is implemented as it's own CShtml view, so you have full control over the output and can add your own fields and sections by registrering them in the custom documentation pipeline.
See it in action in this short video.
Source Code is on Github in the Sxa Branch here.
Should be easy to pull out the Feature folder and use outside as there are not any dependencies on other projects.
