- Edited
A thought about todays documentation practices based on an example, but really, a matter of common practice.
Yesterday I finally got to upgrade my system after a few days of having doubts about completing my usual daily update procedure. I have a disk with personal data that's using ZFS as a file system and as we all know, the ZFS license is not compatible with Linux, so there's people porting the Solaris layer every day for us to be able to use it.
For Arch there's a specific port called archzfs so you don't need to compile from AUR which is nice but often lacks behind the mainstream kernel for it always has to be compiled specifically for one kernel at a time. For people like me who don't want to wait a few days, there's the automated testing repo which keeps track just nice.
Now the ZFS on Linux package had a version update with a pretty changing behavior in its latest version: from before to this version it would fuse two packages together. (Specifically spl-utils got merged into the ZFS package)
This had me doubt several days if I should update or not because pacman prompted me whether to replace x with y (which is quite common in package updates and usually safe to do) but then also notified me that package y would now be in conflict with package x and if I wanted to delete x. Wait what?
So this is where my philosophical journey begins. I eventually found out on the archzfs Github Repo─where somebody else opened an issue to make sure that that's right before going yes and yes─that it'd be fine to go ahead and delete package x. At that moment I felt that I wanted to comment on how I would have liked to see this severe change in behavior documented on either the Arch Wiki or the archzfs Github Repo.
The only one who answered right away was the author of the very same issue with a rather harsh tonality about how "It's on their front page [He referred to the ZOL Github Tags, Ed.] and reddit is very excited about it." And whether that was "[...] good enough?"
I did not want to argue there, so we eventually got to share some comments about documentation options in pacman. One of the main package maintainers also commented in a constructive manner later on. But no, I do not think it is "good enough".
We got stuck on how it was not possible in pacman to really reach the user before installing the package. But I don't think that's the point. There's a good old README right in the top directory of almost every Github project where you could make such announcements and delete them once they are out of date.
There are a lot of very conventional places for text. Whenever I do a little script, a program or some publication I usually try to ask myself: "What is the possibly most stupid thing one could do with this?" and then try to come up with some verbose information on how to prevent that. As a matter of fact I therefore know that it can be incredibly annoying to keep track of documentation whenever doing updates even more so small ones. But sometimes even the small ones can confuse your users.
I feel that it has become common practice for us developers and maintainers to expect the user to be investigative. For whenever he gets confused about my program he should have informed himself better, or searched the internet for several hours if there really was no fanatic already writing about that matter before coming to me, or having looked upstream; when in reality years old buzz talk is all about user experience. I for one do visual design, typography, front-end development with preprocessors, Node, CMS, templates, linux system services and a bunch of other crap. Am I lazy? Should I have searched the internet well enough when not knowing whether my system will break after accepting to delete a conflicting package?
In the early automobile days and also the early computing era user and service manuals were thick heavy printed books with every possible maintenance step and technical detail documented. Today you won't even find a service manual for your car and it is business practice to prevent you from fixing anything anywhere, be it your car your phone your book shelf or even your very house. We are digital though, we are open source and the written word, like in this forum or any other website, is supposed to be common good and shared intelligence. In fact it is pretty much probable that somebody already wrote about your product. I do not think more and bigger is just better though. I'm a designer at heart. It is about quality. In this case it's about prominence and priority, about user experience.
User experience is providing the user with solutions as fast as possible in a straight forward way as possible with minimal effort. If I cared about my users I could not expect that there may be other sources writing and documenting about my product.
What do you think? Am I overreacting? Is documentation getting better or worse in your point of view? As users, should we put more effort in searching for documentation? As creators, should we put more effort in providing prominent documentation at the source?
This is a general thought and not meant to become a rant about specific cases so please share your thoughts in a general manner.
Yesterday I finally got to upgrade my system after a few days of having doubts about completing my usual daily update procedure. I have a disk with personal data that's using ZFS as a file system and as we all know, the ZFS license is not compatible with Linux, so there's people porting the Solaris layer every day for us to be able to use it.
For Arch there's a specific port called archzfs so you don't need to compile from AUR which is nice but often lacks behind the mainstream kernel for it always has to be compiled specifically for one kernel at a time. For people like me who don't want to wait a few days, there's the automated testing repo which keeps track just nice.
Now the ZFS on Linux package had a version update with a pretty changing behavior in its latest version: from before to this version it would fuse two packages together. (Specifically spl-utils got merged into the ZFS package)
This had me doubt several days if I should update or not because pacman prompted me whether to replace x with y (which is quite common in package updates and usually safe to do) but then also notified me that package y would now be in conflict with package x and if I wanted to delete x. Wait what?
So this is where my philosophical journey begins. I eventually found out on the archzfs Github Repo─where somebody else opened an issue to make sure that that's right before going yes and yes─that it'd be fine to go ahead and delete package x. At that moment I felt that I wanted to comment on how I would have liked to see this severe change in behavior documented on either the Arch Wiki or the archzfs Github Repo.
The only one who answered right away was the author of the very same issue with a rather harsh tonality about how "It's on their front page [He referred to the ZOL Github Tags, Ed.] and reddit is very excited about it." And whether that was "[...] good enough?"
I did not want to argue there, so we eventually got to share some comments about documentation options in pacman. One of the main package maintainers also commented in a constructive manner later on. But no, I do not think it is "good enough".
We got stuck on how it was not possible in pacman to really reach the user before installing the package. But I don't think that's the point. There's a good old README right in the top directory of almost every Github project where you could make such announcements and delete them once they are out of date.
There are a lot of very conventional places for text. Whenever I do a little script, a program or some publication I usually try to ask myself: "What is the possibly most stupid thing one could do with this?" and then try to come up with some verbose information on how to prevent that. As a matter of fact I therefore know that it can be incredibly annoying to keep track of documentation whenever doing updates even more so small ones. But sometimes even the small ones can confuse your users.
I feel that it has become common practice for us developers and maintainers to expect the user to be investigative. For whenever he gets confused about my program he should have informed himself better, or searched the internet for several hours if there really was no fanatic already writing about that matter before coming to me, or having looked upstream; when in reality years old buzz talk is all about user experience. I for one do visual design, typography, front-end development with preprocessors, Node, CMS, templates, linux system services and a bunch of other crap. Am I lazy? Should I have searched the internet well enough when not knowing whether my system will break after accepting to delete a conflicting package?
In the early automobile days and also the early computing era user and service manuals were thick heavy printed books with every possible maintenance step and technical detail documented. Today you won't even find a service manual for your car and it is business practice to prevent you from fixing anything anywhere, be it your car your phone your book shelf or even your very house. We are digital though, we are open source and the written word, like in this forum or any other website, is supposed to be common good and shared intelligence. In fact it is pretty much probable that somebody already wrote about your product. I do not think more and bigger is just better though. I'm a designer at heart. It is about quality. In this case it's about prominence and priority, about user experience.
User experience is providing the user with solutions as fast as possible in a straight forward way as possible with minimal effort. If I cared about my users I could not expect that there may be other sources writing and documenting about my product.
What do you think? Am I overreacting? Is documentation getting better or worse in your point of view? As users, should we put more effort in searching for documentation? As creators, should we put more effort in providing prominent documentation at the source?
This is a general thought and not meant to become a rant about specific cases so please share your thoughts in a general manner.
