Something I have noticed has happened at Microsoft recently has been the drive to release tonnes of new features in Azure and elsewhere but with documentation lacking or lagging, sometimes by many months. This is not acceptable from a business point of view but is common in code-driven organisations where success is driven by the number of lines of code that are deployed each day.

The DevOps philosophy hasn't helped because with all the drive to automation and release rate, documentation is not really mentioned. Sometimes you get a, "things should be self-documenting" but that is evidently never true ever! Even MSDN documentation produced from code is woefully inadequate without remarks and examples, all of which have to be manually thought of and added.

Microsoft have moved lots of projects to github, including their main documentation but even raising issues against simple things like changing explanations slightly or adding a single comment can take weeks or months (and in one case, I waited months to eventually be told that the repo was then moved and I had to submit it again). All of this evidence points to an organisation, and am guilty of the same thing, that does not take good documentation seriously.

There is no way that a change to the UI of an Azure blade should be released until the instructions are checked and updated accordingly but it is happening all the time. I even found some documents about adding App Insights to JS and the documents don't actually match the snippet that I have so I have raised a ticket to try and clarify but suspect I will get the, "we will add it to the list".

If you are a company that sells B2C then you need to have a serious set of documentation that is easily updated, especially for clarifications and to help people on support tickets. You need to ensure that features that require docs changes are marked accordingly and not released (or even started) until the docs are ready.

Now to work out how to do that...