I really disagree with Microsoft's approach of homogenizing their products, and this is a perfect example.
- There's never a need for "Microsoft" documentation -- you'll have a question with a specific product or service. They really should be distinctive visually.
- This is on the microsoft domain and top left click goes to microsoft.com, but you can't get back here from microsoft.com
- By the time I click through to something (for example, .NET->F#->Get Started), I have not one but two major navbars and footer featuring prominent links and menus completely orthogonal to what I'm viewing. There is nearly zero typographical variation among the content I've expressed interest in (F#), and tons of variation for this separate content. This is distracting.
If I ever get up the nerve to give it a real try, I will certainly test the slack's patience for stupid questions :)
The .NET reference is useful if you are reading through code and maybe to modify it slightly, but I find it (and class hierarchy style docs in general) to be close to useless if you are writing new code and new to the library. Using a new library in Python (especially one that's heavily object oriented), I often find it easier to learn from tests instead of the docs. Reference docs are often inaccurate or too verbose or show no sense of importance or are just poorly written. Tests are straight to the point, include examples, and tend to focus on the most important parts of the library.
The MSDN docs have quite a bit of "How do I..." content, but unfortunately F# is seemingly always blank as an example.
Combine this with a huge proportion of commonly used third party libraries being .NET rather than F# libraries, and so much of the .NET infrastructure you need to use being C# focused, and as a newcomer you are paralyzed.
If F# is serious about building a community of more than just C# converts, they need to recognize that the convenience of .NET for people who already know it carries a commensurate tax for everyone who doesn't. It's harder for me to learn .NET as an F# user than a C# user. It's harder for me to learn to use NuGet as an F# user than a C# user. It's harder for me to learn to use Visual Studio as an IDE with F# than C#. In everyone of these scenarios, you're running up hill because examples and documentation and interfaces are all for the majority, which you won't be.
Curious about this also. Last time I took a peek at F# I wanted to make a simple game, but all the compatible tools seemed like C# tools that allegedly work for F# as well. Wound up using Lua/LOVE instead.
It's very hard to do it along the way if you aren't familiar with C# either. Now you're struggling to get your head around both paradigms as well as however the thing you're trying to do works.
I doubt I would have ever stuck with Clojure longer than a day, for example, if it wasn't for this library. It's not very long and all the functions are very short, but it meant that everything I needed from the file system was a 30s peek at the documentation and exactly what I expected rather than ~30+ minutes futzing with Java and forgetting what I was doing in the process https://github.com/Raynes/fs
Definitely. Understanding Clojure/Java interop to consume a library requires that you understand both Clojure and Java far more than you would need to if you were to consume a library native to whatever you were using.
I definitely agree. Trying to jump into F# without any knowledge of .NET just requires so much mind-juggling. As a beginner, so much of the difficulty and frustration comes from the fact that you are missing so much foundation knowledge that you don't know what to ask or look for, and may not even recognize the answer. Interop won't look or behave or be optimized how you expect and will just wreak havoc with your attempts to build a mental model of what you're learning because of the strange inconsistency.
Sometimes the answer is just so obvious to people who have that foundation knowledge that no one else has bothered to ask on reddit/stackoverflow and you are googling into the wind. Sometimes the only thing you can find is several years old and giving advice that's no longer correct. I'm not sure which is worse.
I had the same trouble trying to build a learning project in Clojure. I remember when starting, I had only used pip and apt-get (and not knowing them well), I didn't even recognize Leiningen as a package manager. It worked so differently from what I thought I needed (and billed itself as a "project automation and configuration tool") that I didn't even recognize it was the solution to my problem.
It's just so easy to take for granted how many things are obvious to us that make solving problems in our comfort zone easy for us and paralyzing for another person, and I think this bias finds its way into the documentation and mindset of entire communities. This makes it harder and harder for something to be approachable if you don't fit in that same box. I'd love to love F#, (I read F# for fun and profit and worked through the F# Koans, but haven't made anything), but I'm not sure if I'll ever get over the hump unless I find myself working somewhere that's already using it. My feelings on Python are somewhere between ambivalent and bitter by now, but the work gets done, I know what to expect, and I never feel lost.
What would really help me, I think:
- More "idiomatic" wrapper libraries around .NET libraries, even if they're slower or have less features/customization.
- Pure F# libraries of typical utilities or ports of popular libraries in other languages, even if they are slower or have less features/customization.
- Content about F# project management from the perspective of someone who uses Python. This is how you do it in Python, this is how you do it in F#, this is why, these are the pros, these are the cons, these are just different because that's the way it is.
- Microsoft got so good and prolific at fighting on their terrain, they overspecialized and forgot how to win anywhere else. Once their opponents stopped stepping on their terrain, MS started losing.
- There's no such thing as the first browser war or the second browser war or the operating system war, and there's no such thing as winners or losers. There's just a never-ending sequence of skirmishes and battles.
I always liked orthodox and unorthodox. I think there are lessons when Sun Tzu discusses cheng/chi that are somewhat orthogonal to the OODA loop, but I see the stated interpretation by porpoisemonkey as a "subset". Lulling your opponent into complacence with the obvious and baiting him into a lethal trap absolutely fits the definition of destroying their perception of reality, but isn't the only way.
Your opponent becoming so paralyzed by the fear of not knowing what you will do next and thus doing nothing also fits the OODA loop in a completely different way, but isn't really cheng/chi. This is also touched on in Art of War, so it's not like they are conflicting ideas.
In a perfect information, turn-based game like Chess, there are no secrets. You know where all the pieces are, who moves what when, and the goal each person has. Direct subterfuge is simply not possible.
Chess masters use unpredictability, but in a perfect information, turn based game, unpredictability is indistinguishable from other traits like adaptability or position. Furthermore, their "tricks" are aimed at achieving proximal goals -- capturing a pawn, splitting a bishop pair, a better position. These proximal goals are then leveraged for victory. This speaks more about chess (or other, perfect information, deterministic, turn based, head to head games) than about mastery in general.
In a game where much information is hidden and victory can be sudden and swift, optimal strategies will take absolutely take advantage of deception, aggression, and risk taking.
I'm hating on your analogy, but I agree with your message. In most games, predictable things are predictable because they are among the most beneficial and safest courses of action. Doing something unpredictable carries with it the implicit cost of doing something that is materially worse, and hoping you will come out ahead because of side effects such as your opponent's confusion. You're probably much better off focusing on executing those simple, obvious, and predictable things well while your opposition bleeds to death while attempting a never ending cycle of net-negative cunning deceptions.
A head to head game in the vacuum of a single match, like, say, Chess or Go or Starcraft, is conducive to certain kinds of strategies. You have one opponent and no teammates. Your win is his loss. It's black and white, clearer what you're trying to accomplish.
Not all games (or "games", i.e. business) are this simple. There can be multiple players. You may have teammates, or you may need to forge alliances. You may then need to break alliances. There can be multiple degrees of victory or defeat, and multiple paths to victory.
Being unpredictable is inherently scary. It's effective in direct conflict because your opponent must account for more possible future situations, diluting his ability to attack you directly, or thwart your true attack directly.
Exactly what makes this effective in direct conflict, makes it a liability when seeking alliances. People will not want to cooperate with you if they aren't comfortable in their prediction that cooperation will be beneficial, so they'll only do it if the alternative is worse. Being predictable makes it easy for people to work with you. This opens you up to many opportunities for cooperation you'd otherwise miss. When cooperation is essential to victory, this is immensely powerful and puts a hard limit on how unpredictable you want to be if you'd like to win. And heck, in life and business, maybe relationships with people are most valuable trophy anyway, i.e. https://youtu.be/dQw4w9WgXcQ
There's also sort of an "anthology" book on Boyd/OODA called Science, Strategy, and War by Osinga.
You can find some other random content on dnipogo.org and in the web archive for belisarius.com (I don't know why this is down now).
When reading about Boyd and his ideas, I think it's best to focus on the core concepts and reason about applications yourself. He built his philosophy bottom up (he was originally a fighter pilot). Examples like in Certain to Win are looking for parallels that exist coincidentally... or perhaps a better word is patterns ( http://www.dnipogo.org/boyd/patterns_ppt.pdf )
I remember noticing Vuejs using the issue tracker for documentation in the lead up to their release of 2.0.
FreeBSD also does this, which will surprise no one who has ever read the FreeBSD docs.
Also, one of the reasons I asked this question in response to antirez is because the Redis docs are excellent and have been since I first set eyes on the project three or four years ago. I don't know what he's doing or how he does it, but whatever it is, it's working.
This is how I've thought of it as well, why I've been hesitant to do much more so far, and why I'm polling a forum with lots of different maintainers rather than a single person at a single project already.
Because of my skills, I'm not going to stumble onto something by chance where I'm contributing upstream to scratch my own itch and then sticking around. I'm expecting I would need to spend time to find a project that seems like a good fit both ways, and become an active user intentionally where without my side agenda I'd be better off using a larger OSS project or a paid service.
I'm cool with putting that time in to help something grow and to help kindred spirits out. I don't want to put in that time just to be a source of annoyance or frustration to someone who's already done me and the world a solid by putting something cool out into the world.
Documentation is where it seemed to me like the best first step, and what people are saying here as well. As a followup, what's the general consensus on the least bothersome approach? Editing/prettifying existing documentation; appending to existing documentation (adding diagrams or examples); or creating "newbie docs" (how do I install this, how do I compile this on Windows, or aggregating a central FAQ from closed issues); or perhaps something else?
Do you think there's room for contributors to OSS outside filing bugs and making pull requests?
I'm a technical product/project manager by day and a hobby programmer by night. Things like writing documentation, triaging issues, coordinating teams, and planning releases is my bread and butter. I'd like the idea of spending time on an OSS project(s) that I find interesting, but I wonder if this is the kind of thing that would be welcome or even considered helpful. OSS projects are passion projects, and it feels like trying to help out uninvited with management tasks would come across as asserting ownership.
I do try to contribute what I can, but they're small hit and runs -- update deprecated information in documentation or add some examples, add more information to bug reports, etc., but I'd like to do more. Just without offending anyone :)
- There's never a need for "Microsoft" documentation -- you'll have a question with a specific product or service. They really should be distinctive visually.
- This is on the microsoft domain and top left click goes to microsoft.com, but you can't get back here from microsoft.com
- By the time I click through to something (for example, .NET->F#->Get Started), I have not one but two major navbars and footer featuring prominent links and menus completely orthogonal to what I'm viewing. There is nearly zero typographical variation among the content I've expressed interest in (F#), and tons of variation for this separate content. This is distracting.