Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.


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...


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-s...

Having said that, 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.


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




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: