Email: Password: Remember Me | Create Account (Free)

Back to Subject List

Old thread has been locked -- no new posts accepted in this thread
Richard Erlacher
04/17/12 23:03
Read: 684 times
Denver, Co
USA


 
#187200 - Nothing has changed since 15 years ago ...
Responding to: Per Westermark's previous message
Per Westermark said:
Richard Erlacher said:
People involved in open-source development have in very recent months freely admitted that their documentation lags quite a bit behind the released software.

What people? Random, anonymous coders?

I was briefly in a discussion group focusing on documentation, where I offered to work on documentation to make the then-current release of the subject open-source software align with the by that time somewhat outdated user doc's by whittling on the doc's. As usual, key words, such as "not" had been omitted in places.

Nobody was interested even to the extent of providing information as to where the underlying documentation could be located.

While there has been some time that's passed since then, I doubt there's much change in attitudes.


Richard said:
This condition persists because the people doing the work are coders, and coders seldom enjoy documenting their work ...

And your view on all the sites specializing in documentation?
Or the long list of people participating in the documentation for different open-source projects - not as coders?

Richard said:
in fact, nobody really enjoys it, do they?

And people selecting this for a living? You have interviewed a significant group of such people?

I've not "interviewed" such people, but I have had them under my supervision over the past few decades, and have gathered from their attitudes that those who write code don't like to have to document it.

BTW, the reason for my lack of opinion about the current LINUX is because I'm unable to use it much, largely because of the lack of user documentation.

I have asked before and ask again - what documentation are you missing? There are millions of pages of documentation available about the Linux kernels, the system tools, the graphical environment, lots and lots of applications, specific Linux distributions etc. So why not be more specific and show that you really have multiple, explicit examples of common (so they do relate to Linux) tools/applications/configurations/xxx where there aren't enough documentation available to make full use?

That's where it's most obvious that the current used documentation is still several releases behind the released executable software. It's difficult to find documentation that provides basic information about how the software was intended to be use. There's plenty of information about installation and configuration, but precious little about what to do and how to do it.

Last example was of an unknown getty from lots and lots of years ago.

That was the first, and last, time I involved myself in "whittling" on a LINUX component. That was in '94-95, by which time LINUX was already quite popular and had at least three separate commercial distributions. It's not like it was new and fresh. I've looked at both code and doc's since then and seen little improvement in relative lag between doc and code. I'm still persuaded that this is because code precedes doc's.

By the way - I still haven't heard any view you have about LDP - Linux Documentation Project.

Just because there's a LDP doesn't ensure that the last-released doc's are in any sense current.

Or what issues do you see with the documentation for all GNU tools?


I don't see any issues other than those mentioned. I've looked at a few GNU tools, e.g. GIMP, but find the same things among the doc's that I see in other open-source projects. With GIMP, I found that there's more emphasis on what one can do than on how to do it. That's only from a superficial inspection, however.

I freely admit the doc's for Windows are no better. Most of what exists was 3rd-party-generated. It's just the underlying user-interface principles have changed so little since the original versions, that people can "get by" much more easily. That's not ideal, but it's the way it is. LINUX components originate, to some extent, from *NIX where people did things in such a way as to make their efforts impenetrable, thereby ensuring job security. I've met few *NIX (including LINUX) users who felt that typing six lines was better than typing a dozen.

RE



List of 92 messages in thread
TopicAuthorDate
has linux had its chips?      Jez Smith      04/06/12 05:09      
   some weirdo in sandals a ponytail        Andy Neil      04/06/12 05:38      
      Problem is      Jez Smith      04/06/12 06:16      
      possibly, but not only      Erik Malund      04/06/12 08:11      
      It's all in the history ... and "read the code" doesn't work      Richard Erlacher      04/06/12 16:39      
         Good points!      Andy Neil      04/07/12 14:48      
            Why not a firm objective?      Richard Erlacher      04/08/12 00:32      
               Lots of projects have a large percentage research        Per Westermark      04/08/12 14:58      
                  I knew you'd have to come in with something irrelevant      Richard Erlacher      04/08/12 19:29      
                     Try document an invention before it's invented...      Per Westermark      04/08/12 20:16      
                        Here's some research for you, Per      Richard Erlacher      04/09/12 13:03      
                           Richard to give an example      Erik Malund      04/09/12 13:16      
                              I'd like YOU, Erik, to come up with one example ...      Richard Erlacher      04/09/12 13:42      
                                 Always prejudice from Richard      Per Westermark      04/09/12 23:14      
                                 'documenting' means many things      Jim Granville      04/10/12 01:11      
                                 here we go again      Erik Malund      04/10/12 08:00      
                                    when you're wrong, you're wrong      Richard Erlacher      04/12/12 10:52      
                                       I do not have a microscope and probes that small      Erik Malund      04/12/12 12:30      
                                          So you've made no observations ... you just guessed ...      Richard Erlacher      04/15/12 02:22      
                                             and that irks you immensely      Erik Malund      04/15/12 06:33      
                                                What did you do, aside from guessing?      Richard Erlacher      04/15/12 09:04      
                                                   then please, tell me      Erik Malund      04/15/12 15:45      
                                                      Are you willing to explore this in detail?      Richard Erlacher      04/16/12 09:07      
                                                         now you are jumping      Erik Malund      04/16/12 09:38      
                           Your references aren't exactly backing your view      Per Westermark      04/09/12 23:39      
                              It's not about me ... it's about process      Richard Erlacher      04/10/12 00:08      
                                 But processes contains feedback loops      Per Westermark      04/10/12 00:56      
                                    I believe you've gone off-the-rails, Per      Richard Erlacher      04/12/12 11:04      
                                       But getty isn't Linux      Per Westermark      04/12/12 11:28      
                                          it's a small piece, but it's an example      Richard Erlacher      04/15/12 02:10      
                                             But not of Linux      Per Westermark      04/15/12 07:08      
                                                It was part of the distribution.      Richard Erlacher      04/15/12 09:06      
                                 'Research' can mean many things      Jim Granville      04/10/12 01:00      
                                    Yes, but that's in a different context      Richard Erlacher      04/12/12 11:11      
                                       You still haven't told what Linux documentation you miss      Per Westermark      04/12/12 11:44      
                                          I don't know what you mean      Richard Erlacher      04/15/12 02:28      
                                             Still claims based on assumptions and not facts      Per Westermark      04/15/12 07:19      
                                                Not everyone is completely stupid      Richard Erlacher      04/15/12 08:28      
                                                   But what is the relevance today?      Per Westermark      04/15/12 10:08      
                                                      I've no opinion about the current LINUX      Richard Erlacher      04/16/12 09:16      
                                                         and, you Richard, who loves living in the past      Erik Malund      04/16/12 09:40      
                                                            just a minute, Erik      Richard Erlacher      04/17/12 09:36      
                                                               Examples?      Per Westermark      04/17/12 10:42      
                                                                  Nothing has changed since 15 years ago ...      Richard Erlacher      04/17/12 23:03      
                                                                     at least not Richards opinions :)      Erik Malund      04/18/12 07:42      
                                                                     Still lots of assumptions and unbacked claims      Per Westermark      04/18/12 11:59      
                                 Oh, Richard, I have a job for you      Erik Malund      04/10/12 08:14      
                           I had Yourdons first book as manuscript and ...      Erik Malund      04/10/12 08:11      
                              be careful ...      Richard Erlacher      04/12/12 10:23      
                                 were you once a bartender ...      Erik Malund      04/12/12 10:47      
                                    You have to accept the difference ...      Richard Erlacher      04/12/12 11:14      
                                 We are careful      Per Westermark      04/12/12 11:01      
                     Hog Wash.....        Michael Karas      04/08/12 21:57      
                        Odd that you see it that way ...      Richard Erlacher      04/09/12 11:24      
                     I just documented fully      Erik Malund      04/09/12 06:43      
               Because an "Objective" is not a final product specification        Andy Neil      04/09/12 02:36      
                  I have to disagree ... the objective specification is step 1      Richard Erlacher      04/09/12 11:36      
            documentation        Andy Peters      04/09/12 11:02      
               Definitely not the "usual response"      Per Westermark      04/09/12 22:47      
   Android      Joseph Hebert      04/06/12 09:31      
      I don't think so      Jez Smith      04/06/12 12:58      
         Don't agree      Per Westermark      04/07/12 07:05      
      all due respect, no.      Andy Peters      04/09/12 11:11      
         Apple may have a price match on the superluxourious      Erik Malund      04/09/12 11:40      
            re: Apple may have a price match on the superluxourious      Andy Peters      04/11/12 18:31      
               but 95% of the population does not need....      Erik Malund      04/12/12 07:35      
                  Web browsing normally the most power-hungry you can do      Per Westermark      04/12/12 10:32      
                  re: 95%      Andy Peters      04/12/12 10:40      
               So how exactly am I wrong?      Joseph Hebert      04/12/12 08:11      
                  But Android is Linux      Per Westermark      04/12/12 10:41      
                     Just the opposite        Joseph Hebert      04/12/12 12:11      
                        {sigh}      Andy Peters      04/13/12 10:42      
                           just like the preacher said to the atheist      Erik Malund      04/13/12 11:13      
                  re: How exactly?      Andy Peters      04/12/12 11:51      
      850000 Android phones activated per day, linux video      Frieder Ferlemann      04/09/12 11:25      
   anecdotes...      Jim Granville      04/06/12 15:29      
      These guys...      Jez Smith      04/07/12 01:40      
         digital audio consoles      Andy Peters      04/09/12 11:13      
   The Rasperry Pi Foundation clearly doesn't think so!      Andy Neil      04/09/12 02:41      
      The world isn't just a few companies      Per Westermark      04/09/12 06:47      
   the basic problem with free software is...      Erik Malund      04/10/12 08:33      
      Careful with the use of "Linux". Most things "Linux" aren't!      Per Westermark      04/10/12 08:53      
         I did refer to linux itself      Erik Malund      04/10/12 09:06      
            Wrong hw selected, or just big lack of platform knowledge?      Per Westermark      04/10/12 12:54      
               a port      Erik Malund      04/10/12 13:10      
                  Always danger with low-level code for platform      Per Westermark      04/10/12 14:32      
      True - but "paid-for" is not necessarily any better!      Andy Neil      04/10/12 13:31      
         when selecting any tool      Erik Malund      04/10/12 13:44      
      As Stallman said.....      Steve M. Taylor      04/11/12 15:59      
         free      Erik Malund      04/12/12 08:11      
            All about volume or already existing knowledge/experience      Per Westermark      04/12/12 10:37      
   Well...say what you like about me, and many people do.        Jez Smith      04/11/12 14:43      

Back to Subject List