Sunday Surprise – Treat docs like code


TypewriterThere has been a trend recently to start treating documentation like code. This is especially true in open source projects where they are trying to get the developer community to contribute content to the documentation set.

Just like open source code projects, these documentation workflows follow a similar pattern: a single author posts a document, edits are made by others and pushed up to the main article, reviewers check all contributions to make sure it is accurate and that it follows conventions, and the credit is shared by everyone.

If this sounds somewhat familiar it is because this model has been used by the TechNet Wiki since the beginning. The site takes an article created by one person, lets the community edit it, and then it is shared with the world. This collaborative documentation method has been extended by Microsoft to its other sites including developer documentation for ASP.NET and Internet Explorer. Microsoft Azure docs now live on GitHub and the Azure team encourages the community to actively edit their documentation.

Stack Overflow has just announced a similar Documentation area on its site asking the community to submit articles and code samples on all types of technology. The lines are blurring even more now that Microsoft has partnered with Stack Overflow on some API reference content. And one writer argues Stack Overflow has now gamified the collaborative approach to writing docs.

So where does TechNet now fit in this brave new world? TechNet Wiki differs from these other sites as we still need to police ourselves. Microsoft Azure documentation uses both pull requests to accept changes and reviewers to make sure the content is exact, For the TechNet Wiki, it is up to us to make sure that our documents are high in quality and are accurate. This only comes through vigilance and hard work.

Comments (6)

  1. pituach says:

    Very interesting subject for discussion 🙂
    “treating documentation like code” in the sense of shared document that can edit by several people, is the basic idea of any WIKI. Not just the TechNet WIKI. Moreover, Not any WIKI is open to all public. There are lot of groups (and companies) that uses “WIKI like” interface to work with internal documents 🙂

    1. The main difference though between a Wiki and docs housed in a central repo is that there may be gates preventing you from modifying documents. The newer systems for Microsoft and Stack Overflow employ reviewers of edits before they are accepted. Not all Wikis can or event want to do that.

  2. chilberto says:

    Thanks Ken. Vigilance, hard work and policing ourselves – sounds like a good recipe!

  3. Great food for thought! Thanks, Ken!

Skip to main content