One of the perks I experience from being in front-end development for so long, is that I'm not scared of documentation anymore, no matter how boring it looks. It's easier to get started with new libraries and / or frameworks and I recognize if I actually like doing something way quicker.
It also made me realize that documentation and versioning is really confusing, and apparently quite hard.
And it's not just software, but even the languages we use. A few years ago, a lot of us never heard about Ecmascript before. Now we're all aware of 'ES' versions like ES6, which also is named as ES2015 and ECMAScript 2015. You might not realize it, but having three names for one thing is confusing for newbies. Hell, it's confusing to me. I just took the fact that ES6 and ECMAScript 2015 are the same thing at face value, but when looking up information the first time I wasn't sure if an article that exclusively talked about ES6 was talking about the same thing as blog post exclusively talking about ECMAScript 2015. (note how I wrote ECMA both capitalized and not, because that's apparently how it works)
If we're talking about frameworks we see that iterations move quickly and the documentation always lags behind. And that's not just the official docs, but also all the blog posts that explain how to do particular stuff in the old methods. I was totally confused finding React examples with
React.createClass and just simply
extends Component. It took me a while to figure out what exactly had happened there.
When talking tooling I came across a good example in BabelJS. I'm currently writing an article about transpiling (or compiling as these words are not the same but are used interchangeable) so I find it important to get things right. When you look at the Babel site it tells you to install
babel-preset-env. When you go to the
babel-preset-env Github page it tells you its deprecated and you should use
@babel/preset-env. Confused yet?
Henry Zhu@left_pad@ardennl @svensauleau would just mention that we are in the process of converting to a new site and will add versioning to docs because we are definetely aware there are issues and that it *is* confusing, so frustration is understandable but we are working on making that easier github.com/babel/website/…01:16 AM - 29 Jan 2018
Of course we want our software to improve, become better and make some breaking changes every once in a while, but my big question is: How can we make sure that there are not a whole bunch of people ending up confused because they're looking at conflicting documentation?
I'd suggest that software creators / OSS maintainers should at breaking changes to the official documentation and not just in a changelog. This, of course only works if the official documentation is up to date.
And as open source users we must not forget we can actively contribute to documentation. In fact, most OSS maintainers would welcome help with documentation a great deal!
I'm hoping to write up a bit more on this matter, so I would love to hear your input on this.
sorry if anything is unclear, I wrote this before coffee