Read: 180 times
|#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.
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?
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.