Development Documentation

last updated 1 year ago

Microsoft's documentation on how to setup MSAL is...awful. It takes forever to find any kind of page that has a reference to the specific api methods on their sdks and the github is terrible. There are many dated examples with an absolutely insane amount of code with a "ya just uhh look at the example project and figure it out". People wonder why companies like Auth0 made billions and yet if anyone ever tried to fuck with the "enterprise" shit they'd wonder no more. Convoluted, obtuse, and poorly maintained. The kicker here is that it isn't even that complicated. Most of it is a bog standard redirect flow. It would be so much easier if they had actual documentation rather than random example projects. But what do you expect?

last updated 3 years ago

I had to write some complicated tests that were using Sinon. I have used it a bit in the past and my god. The documentation is just bad. Go to the site and try navigating around or finding something. The UX is just bad. I don't want to shit on stuff too hard but it is BAD. Just go to the releases. It has a docs button and a download button. What does download do? It fucking opens the unminified dist file in a new tab....WHY!??!?? Who needs that? What use is that? Oh, do I need an old version? Should I copy and paste it from the browser? We can version via a package manager! This isn't the early 2000s. Terrible. What does the "Docs" button do? Well, it takes you to the docs for that version. But you know what I was looking for when I clicked on that? The change log....to you know....find out what changed. Instead, I just get the exact same docs site....with who knows what difference. The change log does exist just in the repo. Why not have that exposed on the site like most other libs? I know it is an old library but the docs and lack of modern functionality caused me to kick off an initiative ripping it out of our codebase.

last updated 3 years ago

Another node test runner. I like the docs and site. It gives a good intro to how it is an opinionate framework and that not all opinions need to be the same. While I am not a fan or more so am neutral on the "Tap Protocol" it does give a nice read up on what it is all about...although I still don't get the value. But then again, I am a bit slow. The documentation does a great job outlining where to start with a natural progression into where I'd want to go next. I like how the second section after getting started is about structuring tests. It is great to go right into actual code examples have how the framework is used or "should" be used. The writing style is quite nice as opinions are given with leaving room for others to not feel as strongly on said given opinion. The layout works well. Good old side bar rail that sticks with you as you scroll. Mobile works the way I would expect it to as well. Nested sections could be collapsible however I don't think there is enough that it is warranted. One part that would be nice if there was an explicit example with each assert api showing how to use it. Sometimes the api signatures in js with optional arguments etc can make it a little hard to know the "right" way of doing something or the right way of doing something that requires the optional stuff. Over all it was a good read and another well done bit of documentation for a tool. Note, I have not used the tool and only read the documentation for evaluation purposes.

last updated 3 years ago

The tool is cool. I like it and it is simple to use. The docs do that "everything in one page with a side rail" approach but for desktop they have a major issue....the rail on the side does NOT follow you when you scroll down or click on something. So if I want to go to another part in the doc....I have to scroll all the way....to the top again. This is trivial to fix and really bothers me. Maybe I'll submit a PR but likely not. Otherwise the pacing is good. Easy to just keep scrolling down to learn more. There is a button on the right called documentation which takes you nowhere since the whole thing is all the docs...likely should just remove that. There is not icon or any kinda of brand flare other than a color. It does the job but just that. Update: had to ding another score off since on mobile the navigation is even worse. Instead of having a little icon that pulls out or down the navigation it just has navigation at the top... Another update: I think they just use some tool which generates the site from a markdown file. That tool is crap. Docs are ok. Giving it another + 1 back

last updated 3 years ago

Ok, I may be a little salty here. Suffice it to say that the documentation is decent but the product is meh. I honestly don't know why anyone would use wdio but I digress. Their documentation is actually good. They have a plethora of features which can be overwhelming but generally, if you just skim the different categories it isn't too hard to find what you are looking for. Reports? Go to reports. Integrations? Whatever services are, they have those too. Some weird rarely used test runner in a language we all honestly hate? They probably have a specific plugin or example for that. The times I ever struggle using wdio were generally Selenium's fault and not wdio. A good example of a nontrivial thing I had to do once was use their mocking api for network requests. I wanted to mock specific backend api errors for integration tests. I did stumble a bit with how their filtering works for knowing whether to mock a request, the documentation was extremely helpful. A major issue I did run into was with versions. They are not as much to play as google is. See, most links in google will point to older docs versions and not the latest. And well... Yup, I spent many a hour wondering why I couldn't find some method name or whatever only to look and see the wrong documentation version. Sure, special google searching could help and sure it isn't really wdio docs fault but I wasted many hours from this where as other documentation sites didn't have as much of an issue with this. To be fair they also did not have so many features. I still would give them an A. Very well done.

last updated 3 years ago

Nextjs has wonderful documentation. Their getting started keeps it simple with just giving a single page that shows text. Then they point you towards the next thing you may want to do. The site is snappy to use and works well enough on mobile which is what I often read the most documentation with. They keep a good balance with code snippets to text ratio. I cannot stand when I am looking at giant blocks of source code. Nor do I like clicking on a million codepen/codesandbox links just to see a few specific lines. I did run into a few issues with their more "advanced" features but it wasn't too frustrating to get past them. As is often the case, I wanted to do something that they didn't explicitly have a "copy this" example with. The fact that they usually do have that kind of ease of use is amazing. This is a place I often go to when I think of good documentation.

last updated 4 years ago

This is a prime example of style over substance. The landing page is ok but once you actually need to dig into docs it is awful. To be fair I was looking at the react documentation for this but literally the example code just doesn't work. Again, this is more of looking at the react docs for it. Maybe the pure js are good but ehh...glancing at them...gross. Not only that but the navigation makes no sense. It isn't intuitive at all. Pretty colours. Awful docs.