3 ms·

I have been trying to optimize a initContainer written in NodeJS and one of the experiment I am trying out is to rewrite it in .NET Core and Microsoft's documen

I have been trying to optimize a initContainer written in NodeJS and one of the experiment I am trying out is to rewrite it in .NET Core and Microsoft's documentation has been pretty good - it is clear, well organized, gives you examples for each API and there are how-tos for things that people typically care about - the architecture docs linked from here for e.g. https://docs.microsoft.com/en-us/dotnet/ https://docs.microsoft.com/en-us/dotnet/ API docs example -https://docs.microsoft.com/en-us/dotnet/api/system.collections.concurrent.concurrentqueue-1?view=netcore-3.1 https://docs.microsoft.com/en-us/dotnet/api/system.collectio... I find the Python docs and tutorials good as well. But that's to be expected for mature language/ecosystem like Python. Good documentation is a lot of work and skill and it's a thankless job for the most part. So it's really amazing when organizations / OSS communities get it right consistently.

gregmac 6y ago
Microsoft has put lots of effort into their docs in the past couple years, and it's pretty great. Under the "Version" dropdown you can flip to see the same docs in a specific version or platform (Framework vs Core), and this is pretty helpful for porting/upgrading code, as well as coming from a Google search or Stack Overflow link -- you can easily get to the docs for the version you're working with. The other great thing they've done is published all the .NET code on https://source.dot.net https://source.dot.net, so you can dive into the code for ConcurrentQueue<T> [1] for example. I sometimes find looking at the source is a faster way to answer a specific question about how something works vs reading through several pages of documentation, where the nuance I care about is noted in a "Remarks" section which is easily missed. [1] https://source.dot.net/#System.Private.CoreLib/ConcurrentQueue.cs,18bcbcbdddbcfdcb,references https://source.dot.net/#System.Private.CoreLib/ConcurrentQue...
- blinkingled 6y ago
  Yes, the version dropdown is a godsend especially for .NET as there are many variations - If I want to see if the API exists or is different on say .Net Core vs .Net standard this makes it a piece of cake. Also wasn't aware of the source browser - some questions are best answered by - use the source, Luke - and you might get better ideas for your own code from there :)
- CobsterLock 6y ago
  Personally I keep a .NET decompiler on my taskbar. I was about to say I like being able to find all references and usages of internal variables, but I see now the site does a pretty good job. I also like directly seeing how my code utilizes the library functions (not just the .NET libraries, sometimes nuget packages too). The decompiler also removes ambiguity of "what code is actually being ran". ILSpy has worked nicely for me, it has the extra perk of having nice integration with LINQPad (another must-have for .NET developers)
  - gregmac 6y ago
    ILSpy + LINQpad is my go-to as well, and I actually still use ILSpy more often than source.dot.net. It's nice to be able to send a link to someone else though, and the site is well done, fast, and has a great domain. :)
- cesarb 6y ago
  Is there an offline version of that documentation? One of the best things about Java is that you can install the documentation package (depending on your distribution, it's something like java-11-openjdk-javadoc) and the source code package (something like java-11-openjdk-src), and have an offline copy of the full documentation which you can open directly in your web browser and IDE.
  - blinkingled 6y ago
    Looks like with Visual Studio installation this should work? - https://docs.microsoft.com/en-us/teamblog/offline-book-refresh-feb-2018 https://docs.microsoft.com/en-us/teamblog/offline-book-refre...
draw_down 6y ago
I'm not so sure about that last part. My guess would be that this is down to the difference in incentives between an open-source project and a profitable enterprise. In such a way that we may even expect this to be the common case, rather than an anomaly. Every doc writer Apple hires has to go on a P&L statement somewhere, their existence must be justified every quarter or so, etc. As others have noted, associating this work with the value it generates is notoriously difficult. Of course, some companies may have the kind of culture that understands the value of this work and keeps them around, but open-source projects can accept contributions from whoever offers them without regard for such bureaucratic concerns. Basically, if you write some docs for my open-source project I don't need to pay for your healthcare insurance. The barrier to entry may also be lower for the same reason- if you write some docs, the pull request can be simply merged in. Hiring an employee is a much more involved affair than adding a contributor to the Contributors list in Github.

gregmac 6y ago

Microsoft has put lots of effort into their docs in the past couple years, and it's pretty great. Under the "Version" dropdown you can flip to see the same docs in a specific version or platform (Framework vs Core), and this is pretty helpful for porting/upgrading code, as well as coming from a Google search or Stack Overflow link -- you can easily get to the docs for the version you're working with. The other great thing they've done is published all the .NET code on https://source.dot.net https://source.dot.net, so you can dive into the code for ConcurrentQueue<T> [1] for example. I sometimes find looking at the source is a faster way to answer a specific question about how something works vs reading through several pages of documentation, where the nuance I care about is noted in a "Remarks" section which is easily missed. [1] https://source.dot.net/#System.Private.CoreLib/ConcurrentQueue.cs,18bcbcbdddbcfdcb,references https://source.dot.net/#System.Private.CoreLib/ConcurrentQue...

blinkingled 6y ago
Yes, the version dropdown is a godsend especially for .NET as there are many variations - If I want to see if the API exists or is different on say .Net Core vs .Net standard this makes it a piece of cake. Also wasn't aware of the source browser - some questions are best answered by - use the source, Luke - and you might get better ideas for your own code from there :)
CobsterLock 6y ago
Personally I keep a .NET decompiler on my taskbar. I was about to say I like being able to find all references and usages of internal variables, but I see now the site does a pretty good job. I also like directly seeing how my code utilizes the library functions (not just the .NET libraries, sometimes nuget packages too). The decompiler also removes ambiguity of "what code is actually being ran". ILSpy has worked nicely for me, it has the extra perk of having nice integration with LINQPad (another must-have for .NET developers)
- gregmac 6y ago
  ILSpy + LINQpad is my go-to as well, and I actually still use ILSpy more often than source.dot.net. It's nice to be able to send a link to someone else though, and the site is well done, fast, and has a great domain. :)
cesarb 6y ago
Is there an offline version of that documentation? One of the best things about Java is that you can install the documentation package (depending on your distribution, it's something like java-11-openjdk-javadoc) and the source code package (something like java-11-openjdk-src), and have an offline copy of the full documentation which you can open directly in your web browser and IDE.
- blinkingled 6y ago
  Looks like with Visual Studio installation this should work? - https://docs.microsoft.com/en-us/teamblog/offline-book-refresh-feb-2018 https://docs.microsoft.com/en-us/teamblog/offline-book-refre...

draw_down 6y ago

I'm not so sure about that last part. My guess would be that this is down to the difference in incentives between an open-source project and a profitable enterprise. In such a way that we may even expect this to be the common case, rather than an anomaly. Every doc writer Apple hires has to go on a P&L statement somewhere, their existence must be justified every quarter or so, etc. As others have noted, associating this work with the value it generates is notoriously difficult. Of course, some companies may have the kind of culture that understands the value of this work and keeps them around, but open-source projects can accept contributions from whoever offers them without regard for such bureaucratic concerns. Basically, if you write some docs for my open-source project I don't need to pay for your healthcare insurance. The barrier to entry may also be lower for the same reason- if you write some docs, the pull request can be simply merged in. Hiring an employee is a much more involved affair than adding a contributor to the Contributors list in Github.