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.component, 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
Totally understandable.
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
Top comments (5)
There seems to be an undercurrent here on dev.to; I've noticed a few posts about documentation, each recognizing that it is important, but searching for better tools and good practice recommendations.
Clearly there is need for some helpful guidance. I'll start writing a more in-depth post, but in the mean time I can point you to some useful resources:
Hi Elsa, That's great! I think it's such an undercurrent because we often come across these problems. This post is not so much on writing my own documentation as it is about an over complicated learning curve for our favorite tools because documentation is conflicting.
Regardless, these resources are a good help though and might help in contributing to better documentation in open source software.
Another thought, would you think it to be okay to ask someone who blogged about a topic to update their article or add a note that something is out of date?
I think its okay to ask someone to update an article they wrote. Some tools/processes change quickly, while others are very stable. Sometimes (if the original author has moved on from a particular tool) it can be useful to write your own post on how transition a project from an old tool to a new one.
Maybe it's time ot explore what is being done for documentation : tools, best practices, websites ?
Is there any documentations that is considered good or reference today that can act as starting point ?
Very true, this is what I'm trying to do at the moment. I really enjoy the React docs. They seem to be quite consistent and are well accessible and in some cases note in which version the feature was incorporated.