Chris,
I don't deny that people need to know how to navigate through tasks.
What I neglected to add to my e-mail, is that "navigation knowledge"
is better learned from "flash" type clips, rather than through dozens
of pages of text and still-graphics. Perhaps what is needed is a
standard for how documentation is produced to make it easier for
users to learn from - something along the lines of:
- A concepts and architecture document
- An installation clip
- Tutorial clips
- Task oriented clips
I'm just bemoaning the fact that as technology becomes increasingly
complex, the level of documentation has correspondingly risen. The
quality of such documentation, however, has declined; there isn't a
single reason one can blame, but interspersion of concepts & tasks
in documents is one factor. By separating them & using appropriate
media, perhaps we might address some of these shortcomings as an
industry.
Arshad Noor
StrongAuth, Inc.
Christopher Blizzard wrote:
The documentation that we have available covers both "how to navigate
[with the] GUI" and "how things work." All the way from an overview of
how to build your LDAP tree down to a reference of the internal config
settings that drive the directory server.
I suspect that you're saying that you prefer documents that are low
level descriptions of how the system works, and we do have those. But
you're not the only market. There's a fair number of ways that people
tend to directory servers.
--Chris
On Fri, 2005-12-02 at 08:32 -0800, Arshad Noor wrote:
For what its worth, while I have not worked with OpenLDAP at all, I
vigorously support Howard's argument for concise, precise & clear
documentation. The state of technical documentation today is
pathetic - designed more for people to navigate GUI's than to impart
information about how things work. Its reminiscent of cotton candy
- a lot more air than content. Another artifact of the Microsoft
age....
Arshad Noor
StrongAuth, Inc.
Howard Chu wrote:
Yes, the OpenLDAP documentation is sparse, and this is a fatal flaw.
Yes, what documentation exists is terse, and this is a vital strength.
Nobody likes to spend time wading thru docs, and there's nothing gained
from saying in 5 sentences what can be stated in only one. Certainly we
need to work on expanding the scope of the documentation to cover the
numerous holes. But good documentation is concise and to the point, and
the docs I've written are precise. There may be a problem with imprecise
readers, who skim and skip over things when every single word is
crucial, but that's not our fault.
--
Fedora-directory-users mailing list
Fedora-directory-users@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/fedora-directory-users
--
Fedora-directory-users mailing list
Fedora-directory-users@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/fedora-directory-users
--
Fedora-directory-users mailing list
Fedora-directory-users@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/fedora-directory-users
