[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Do have programs have poor documentation?

Thomas Schmitt schreef op 01-01-2017 14:10:


From the viewpoint of "info" programmers it is obvious that you first

have to learn how to use it before you can draw benefit from it.

But the particular user has a particular need to get information about
a particular complex of problems. No interest in learning anything else
before the current task is completed.
Now how shall the provider of software documentation handle this conflict ?
Thank you for being honest about everything. This is the first time I have seen someone actually go into detail about what is so, instead of people just -- pardon me for saying this thing again -- vehemently denying everything you say.
As a documentation writer yourself you must run into this yes. I am sorry it has been such a rough ride. Lol, just kidding :p.
I have never written man pages but your reasoning seems exactly to the point. Something I would recognise myself. Something you run into, right.
There are various approaches from books over wikis to community discussions. As much as they serve additional groups of users, that much they diversify the landscape of available information sources. They begin to contradict, 
spread half-knowledge, or even engage in advertising wars. (The classic
"use original cdrecord" which you can read with many problem discussions 
about optical media.)
I must say here that though the info system is hard to navigate, the MS-DOS help system was not.
This problem was already solved ages ago (in the 80s). The MS-DOS help system was very easy to use and provided what Info should or could provide. Borland Pascal did the same (and equivalents) and although it used slightly different keys, it too was very easy to use. I always had great fun and joy reading those entries and I must have read all the entries in the Borland Pascal documentation just by heart.
I mean just for fun. I would read stuff for fun and I read everything. I have never used Info with one ounce of joy, and not because I didn't try several times. It is just unusable to me.
The Vi help system is also unusable until you learn a few hard-to-learn shortcut keys for navigation. It just doens't make sense. You need to learn the Vi help before you can get help on Vi. 

Really talking of Vim though. But anyway, beside the point.
Yes of course I recognise choosing to use the web as the next alternative. It's not about me, but what seems to me to be common sense. I already said earlier that there are only two system: man and the web. Again, not about me, but it is hard to get out of this line of reasoning now.
I decided for massive man pages and using Google to find public discussions about my software and related topics. If i find such discussions, i try to 
determine impartially the cause of the problem and to propose a remedy.
If that remedy means "use original cdrecord" then be it so.
But in most cases it's "get other media or a new burner drive".


Okay, so you did not host them yourself. That's a very active job.



I dare to contradict. Not your assessment that man vgchange is hard to
digest, but your impression that the programmers or documenters don't care 
for your initial lack of knowledge.
No no, I don't mean to give a broad sweep to everyone. The only encounter I've had with a man-page writer was a good one, and who was interested to hear what could be improved. I also offered my help and did write some improvement (in something) but couldn't find the time and health to continue on with it; but he recognised the problem and initiated some improvements himself or by himself.
I think we will always find that the actual people doing the job understand better what you are trying to say and are also interested in improving. It is often the people on the side who are not those people, who just ... interfere with you reaching the ones who are interested.
It's just the same as customer support representatives not passing information onto real developers.
In these lands; call it the Linux Support Arena, or the Linux Support Agenda even, people on the side take on the customer support role of filtering. They act like they try to get the complainer off of the back of the developer of writer, much like front-desk personnel often does. The real writer or developer however is often much nicer to you and your complaints or observations, of course, true. 

And thank you for being that person too.
I'm not saying writers don't care, but more that the people who do not do the writing (like some of the 2 girls responding in this thread) and so do not experience the difficulties and desire to make the program easily understood themselves, may not understand.
I feel the further you get from the actual job, the less people will understand and claim perfection on behalf of whomever they think they represent, or represent in actual fact.
Not to give any information here but I once experienced the impossibility in that sense of getting through to some research group at university because front desk personnel (student advisers and the like) kept pushing me further to the front and to more official channels. Whereas the actual people I would have had to work with, would have been interested in my words. I know this for a fact. I just couldn't reach them because their assistent(s) kept pushing me away.
The same happens in a hospital: the front-desk receptionist will tell you you are late and nothing is possible anymore. The actual departmental receptionists however who do the actual job will tell you that all is fine. Same day, same moment, same instance. Front-desk = getting you away or telling you it's impossible. The actual people: no problem sir, sit down, we'll help you right away.
Front desk personnel just doesn't understand the personnel actually doing the job, and I feel the same is true of Linux, where "workers" give support in channels such as these, but may not really be familiar with the job they are advising about.
And then they say there is no need for improvement, when the actual workers do feel the limitations imposed by the system.
And are welcoming any efforts, perhaps, by people genuinely interested in suggesting improvements. 



They try to teach us. With limited success. But nevertheless:
"vgchange allows you to change the attributes of one or more volume groups. Its main purpose is to activate and deactivate VolumeGroupName, 
  "
Duh ?
  "See lvm(8) for common options."
Oh. It has family.
  "lvm  provides  the command-line tools for LVM2."
Now it would be time for me to learn some basics about a thing named "LVM2".
A few days later i would possibly be able to roughly understand what the LVM developers invented during the last two decades and how my current problem 
is related to this invention.
Yes I like how you are following the chain of an uninformed reader or traversing the chain of what someone needs to do and encounters, you could also say.
I am not trying to sound as if my perceptions are so important, I have difficulty expressing myself here now.
I mean you are actually looking at what an actual user would see, which is very nice and thankful for me, I suppose. 

So thank you for that, in any case.




But:

you are in some rescue mode that doesn't automatically activate your
volume groups,
Here we see why old programmers try to avoid using fancy infrastructure.
The answer in an ideal world would be: Learn how to rescue yourself before 
the ship begins to sink.
This does not necessarily mean to master LVM and all other probable points of failure. It means to have a fallback strategy that reduces your personal 
stress level in case of emergency.
That is true but it is a very convenient thing to say. I know dependability is important but the level of dependability you require from external sources is directly dependent on the fallability of the software you are using.
This simply means that using Linux, in general, means requiring more fallback measures than for any other system you would use.
If you are locked up somewhere and it is your only computer, Linux becomes a great liability to you and your functioning.
You probably can't imagine the personal stress levels I've had in my life ;-). And most of it, in a certain sense, came from Linux :p.
I just watched some Eddie Izzard show on how computers fail (https://youtu.be/k6C_HjWr3Nk?t=3m35s, direct hit) and he was not even talking about Linux ;-).
Personally I don't just have the time or the ability to prepare everything or to have all my bases covered all the time. Just doesn't work because I'm already in a "depletion zone" and I am really trying to get out of that to the best I can. So every little thing helps.
My day, no my entire week, can be ruined by yet another thing going wrong in the Linux landscape.
What was the last thing? The billion small things going wrong put me off enough already.
In my case it's a pile of backups and the presence of readily configured 
reserve hardware. (I should do emergency exercises more often.)
I'm in an emergency ;-). I don't have time for emercy exercises, they are already here :p. 


Be aware of what you depend on and prepare for temporarily losing it.
In general that just means building up your life. It doesn't really require anything specific most of the time, just more stuff or more people in a general sense, I guess. 


Last year our government renewed its advise to store food and water for
two weeks. I immediately re-assigned my surplus body weight to civil defense 
preparations. Fressen fuers Vaterland ! (= Gorging for the Country !)


I have the water covered ;-). My food storages are in the negative :p.


In the real world of emergencies, your mileage may vary, of course.
Dealing with emergencies like that requires surplus when it is not an emergency.
If you are going to make software (not speaking to anyone here) that is meant to save people yet itself is as fallible as can be...
Well to me those are just broken promises I guess. I am very upset with myself very regularly for trusting the promises of Linux. I often question why I even started on this path. And I berate myself for ever doing so, I guess. 



That's more a problem with the fellow humans than with technical docs.
Nothing is easy if you only dig deep enough into its details.


You mean everything is easy, right.
I had a friend who played chess. ELO rating of about 1900. He would say "It's easy." 1900 is not much. My other friend had a rating of about 22-2300. He would say "Yeah, chess is a nice game, but it gets a little boring". So they started playing bridge and then his sister became world champion.
Everything is easy yes. Except that this statement has never been helpful to anyone.
No it is perfectly possible to design a system that is fail-safe or that gets the required information to you at the required time. It's just not being done. Not enough time for it, I guesss. Not enough time being spent on it, or not enough dedication and attention.
And thus the "emergency mode" problem turns out to be about the need for 
becomming an insider at an inappropriate moment of time.
Yes exactly. And this is always the case with whatever problem. You want to focus on solving your problem and not on spending 26 hours on filing a bug report and discussing it with developers first who want your aid into solving theirs.
When you need a skilled friend, then technical documentation will hardly 
be able to serve as a substitute.
You would be hoping that Linux itself would be that friend, or that rescue system. And then it turns out to be your enemy instead. 

Who wants you to do more work for them before they will help you.
I am sorry I am being so ghastly and negative about this. My mood instantly goes up when I use Windows, because normally (although it has become worse in recent years) Windows just always works.
Windows is less than 50% of what it was a few years ago. I mean its dependability. It is going down the road of Linux and has acquired its developer mindset as well.
The technical documentation of LVM could have solved my issue, but it didn't.
It could have given an overview of the most important tasks to perform, but it didn't.
The Debian (Ubuntu) rescue system is even worse (for Ubuntu 16.04) because it gives a dysfunctional menu that keeps popping up as you're trying to execute commands and gets in your way. And does weird stuff without you knowing why. Just a failing system, just a programming error somewhere. But it means your little rescue attempt fails.
Which can mean you need to boot some full Live DVD and this can cost you much time. I do very little social things in Linux because my Linux is not dependable enough to make "me" available to other people in some predictable way. There is so much stuff that can go wrong that interacting with people is not really possible.
Dependability is the basis of all creation. You can't create when your tools don't work half of the time. You'll spend all of your time fixing your tools instead of doing useful stuff. This is why I often regret I was born or got to use Linux in the first place. Emergency rescue or emergency backup reduces your stress level to a great extent. But if you use Linux, all of it may be unavailble.
I sometimes think I should have emigrated to Italy and drowned in the sea where it was warm.
That would have been a better life than this. Well, anyway, none of your business I suppose...
Reply to: