4 ms·

The vast majority of docs.microsoft.com is written in markdown. This project seems be both very easy to contribute as well as produces a great docs site.

datenarsch 6y ago
MSDN has been around for much longer than Markdown has even existed, so I highly doubt that. Maybe the more recent stuff, which by the way is much much worse from a technical pov than their older technical documentations sadly. Compare the mess that is .NET Core / ASP.NET MVC documentation to the mostly excellent WINAPI documentation...
- hyperrail 6y ago
  Most older pages on docs.ms.com have been converted to Markdown, and yes, that includes the Windows C and COM API docs.* Here's the source code for CreateFile's doc page: https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-src/content/fileapi/nf-fileapi-createfilew.md https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-s... Having said that, https://docs.microsoft.com https://docs.microsoft.com 's flavor of Markdown does allow for embedded HTML, like GitHub's and enough pages still use that feature that the conversion to Markdown is arguably incomplete. It isn't a big issue in practice, however; you can update markup from HTML to Markdown along with your other changes. * As a recent-past engineer on the Windows team, I have a rather lower opinion of Windows API docs than you. :) The Windows developer platform has not had enough dedicated technical writers for years; our developer content teams are mainly editors of engineer- and PM-written original docs, which can lead to API doc sets with badly written pages, important missing information, or references to Windows-internal developer tools. I tried to channel my frustrations into correcting and extending my coworkers' writings, or into gently asking them to fix their omissions when I didn't have the free time to spend on the needed research.
caddywompus 6y ago
Interesting, I didn't know that. I'll check it out, since I'd like to see if they add any of their own extensions, in the same way that Github does

datenarsch 6y ago

MSDN has been around for much longer than Markdown has even existed, so I highly doubt that. Maybe the more recent stuff, which by the way is much much worse from a technical pov than their older technical documentations sadly. Compare the mess that is .NET Core / ASP.NET MVC documentation to the mostly excellent WINAPI documentation...

hyperrail 6y ago
Most older pages on docs.ms.com have been converted to Markdown, and yes, that includes the Windows C and COM API docs.* Here's the source code for CreateFile's doc page: https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-src/content/fileapi/nf-fileapi-createfilew.md https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-s... Having said that, https://docs.microsoft.com https://docs.microsoft.com 's flavor of Markdown does allow for embedded HTML, like GitHub's and enough pages still use that feature that the conversion to Markdown is arguably incomplete. It isn't a big issue in practice, however; you can update markup from HTML to Markdown along with your other changes. * As a recent-past engineer on the Windows team, I have a rather lower opinion of Windows API docs than you. :) The Windows developer platform has not had enough dedicated technical writers for years; our developer content teams are mainly editors of engineer- and PM-written original docs, which can lead to API doc sets with badly written pages, important missing information, or references to Windows-internal developer tools. I tried to channel my frustrations into correcting and extending my coworkers' writings, or into gently asking them to fix their omissions when I didn't have the free time to spend on the needed research.

caddywompus 6y ago

Interesting, I didn't know that. I'll check it out, since I'd like to see if they add any of their own extensions, in the same way that Github does