Michele Petrovsky wrote:
With respect, I have to disagree with some recent comments on this list.
Tools like Git and slack channels have an important role in managing
generations of software. But they don't, and largely can't, focus on
what's most central to good documentation.
I disagree stronly with this. Slack is an online communication tool.
Although we use this mailing list, it is because of the Apache maxim;
"If it didn't happen on the list, it didn't happen". which means that
all decisions, that affect the project, must be made on a mailing lists.
As for git, it is at its core, a Version Control System (VCL), which is
just as necessary for documentation as it is for software development,
especially in a distributed context as we are in. else wise how do we
know who is doing what qand to which piece of the documentation.
Like all written, and even spoken, language, documentation must be readily
understandable. It must flow easily. It cannot get struck in a corner.
At its best it might, by being enjoyable, be even more effective than
anticipated.
Completely agree. otherwise, why bother writing it.
By virtue of my experience in higher education, I'm certain that most AOO
users resemble my former students. Few of them have been tasked with
installing or configuring anything, and so have little interest in, or even
recognition of, tools like Git or slack channels.
I agree, your experience there brings a needed perspective to our team.
However neither of these has any thing to do with system configuration
except tangentially in the fact that they have to be installed; an
experience most every personal computer user has experience with.
Points on being scrupulous about formatting are of course important. But I
think what's even more salient to successful documentation is wording
that's both correct and friendly. For instance, this entry from Calc Chap.
2 (Entering, Editing, and Formatting Data) is an excellent example not only
of how to write a good error message, but also of how to write useful
documentation: (Edits and ellipsis mine.)
On this with agree.
To be of real help to users, particularly inexperienced ones, [error]
messages need to provide details [ ... not only on what went wrong but also
on how to correct it. ]
Again, we agree
<snip>
---------------------------------------------------------------------
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org
