Date: Tue, 17 Aug 2004 14:42:02 +0300 From: Giorgos Keramidas <keramida@FreeBSD.org> To: Niclas Zeising <lothrandil@n00b.apagnu.se> Cc: freebsd-doc@FreeBSD.org Subject: Re: docs/70555: [diff] changes to freebsd-glossary Message-ID: <20040817114201.GC6960@orion.daedalusnetworks.priv> In-Reply-To: <200408161841.i7GIfVvZ033191@www.freebsd.org> References: <200408161841.i7GIfVvZ033191@www.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2004-08-16 18:41, Niclas Zeising <lothrandil@n00b.apagnu.se> wrote:
> I have made some additions to freebsd-glossary. Hopefully i have got
> at least some entries right... ;) Feel free to make changes if
> something is wrong or send me a note to change it.
Nice work!
If you can tolerate my knit-picking we can probably get a lot of good
glossary entries out of this. Let's see what we can do :)
> + <glossentry id="api-glossary">
> + <glossterm>Application Programming Interface</glosterm>
> + <acrponym>API</acronym>
> + <glossdef>
> + <para>A set of routines, protocols and tools to make it
> + easier to develop applications.</para>
> + </glossdef>
> + </glossentry>
Does this look better as a description of "API" ?
"A set of procedures, protocols and tools that specify the canonical
interaction of one or more program parts; how, when and why they do
work together, what data they share or operate on, etc."
> <glossterm>Basic Input/Output System</glossterm>
> <acronym>BIOS</acronym>
> <glossdef>
> - <para></para>
> + <para>A <acronym>ROM</acronym>-chip with basic software to
> + provide an interface between sofware and hardware.</para>
The term BIOS is some times used in an ambiguous manner, with the actual
meaning depending on the context. For some "BIOS" is the ROM-chip
itself, for others the set of routines that are contained there and help
in bootstrapping the system. For others, it might even be the "text
mode GUI" that the user can use to configure the bootstrapping process.
The term is also very PC/x86-specific, so we might want to capture this
in its definition too.
> <acronym>CPU</acronym>
> <glossdef>
> - <para></para>
> + <para>Also known as the prosessor. This is the brain of the computer
> + where all calculations take place.</para>
This is also an oversimplification, but anyway :-)
> <acronym>DNS</acronym>
> <glossdef>
> - <para></para>
> + <para>The system that converst humanly readable hosts to ip addresses
> + and vice versa.</para>
Please fix the typo s/converst/converts/. Perhaps we should add an
example here too:
"The system that converts host or domain names
(i.e. mail.example.net) to IP addresses and vice versa."
> - <para></para>
> + <para>A protocol that dynamically assigns ip addresses to a cumputer
> + (host) when it requests one from the server. The ip assignment is
> + called a lease.</para>
Typo: s/cumputer/computer/. I would also prefer "ip assignment" written
as: "The address assignment is called a <quote>lease</quote>." and IP
capitalized when used to signify the Internet Protocol.
> <glossterm>File Transfer Protocol</glossterm>
> <acronym>FTP</acronym>
> <glossdef>
> - <para></para>
> + <para>Protocol used to transfer files over a network.</para>
I'd probably write this with a bit more detail:
"A member of the family of high-level protocols implemented on top
of <acronym>TCP</acronym>, FTP can be used to transfer files over a
TCP/IP network."
This way the reader knows that FTP works only with TCP/IP networks;
it's clear that it doesn't work (at least not without a TCP
compatibility layer) with IPX networks :-)
> <glossterm><acronym>IP</acronym> Version 4</glossterm>
> <acronym>IPv4</acronym>
> <glossdef>
> - <para></para>
> + <para>The old IP protocol which uses 32 bits for addressing.</para>
I wouldn't call "old" something that is still so widely in use ;-)
Since IPv4 has played such a major role in the development of what
Internet is today, I'd probably like it a lot better if we expanded the
description a bit. My network connectivity at work SUCKS today and I
can't seem to be able to reach Google, but good idea if you're
interested in expanding this a bit is probably to see how Sun, Cisco or
others describe IP in their own glossaries.
We can probably "borrow" ideas if not the text itself.
> @@ -718,7 +739,8 @@
> <glossterm>Internet Protocol</glossterm>
> <acronym>IP</acronym>
> <glossdef>
> - <para></para>
> + <para>A packet transmitting protocol. The basic protocol on the
> + internet.</para>
This should be a reference to "IPv4" since a lot of text that simply
refers to "IP" implicitly means "IPv4".
> <acronym>ISP</acronym>
> + <para>A company that gives access to the internet.</para>
Capitalize "Internet" please.
> <glossterm>Kilo Bits Per Second</glossterm>
> <acronym>Kbps</acronym>
> <glossdef>
> - <para></para>
> + <para>Used to measure bandwith. The Kilo prefix can be changed to Mega,
> + Giga, etc. as nessecary.</para>
===> Mental note to myself:
"Bandwidth" is probably a term that would need clarification for someone
who doesn't know what Kbps means. Do we have a definition of teh term
"bandwidth" in our glossary?
> <glossterm>Local Area Network</glossterm>
> <acronym>LAN</acronym>
> <glossdef>
> - <para></para>
> + <para>Network used on a local area, eg office, home etc. Often refered
> + to as network.</para>
I think that "eg" is not a real word and should be written either as
"i.e." or removed as part of a sentence rewrite. "Referred" is also
spelt with two r's.
> <glossterm>Mail Transfer Agent</glossterm>
> <acronym>MTA</acronym>
> <glossdef>
> - <para></para>
> + <para>Application used to transfer e-mails. The most common and well
> + known is SendMail.</para>
Ok, to transfer e-mails... but where and why? When referring to
Sendmail it's probably a good idea to mention that an MTA has
traditionally been part of a BSD system, that Sendmail is included in
the base system for this reason and that there are countless alternative
MTAs with Postfix, qmail and Exim being the most popular today.
> <glossterm>Mail User Agent</glossterm>
> <acronym>MUA</acronym>
> <glossdef>
> - <para></para>
> + <para>Application used to display and write e-mails.</para>
Used by whom?
> <glossterm>Operating System</glossterm>
> <acronym>OS</acronym>
> <glossdef>
> - <para></para>
> + <para>The underlying programs which controls the computer hardware,
> + memory and so on.</para>
What you describe as "hardware, memory and so on" can collectively be
described as "resources":
A set of programs, libraries and tools that provide access to
the hardware resources of a computer. Operating systems range
today from simplistic designs that support only one program
running at a time, accessing only one device to fully
multi-user, multi-tasking and multi-process systems that can
serve thousands of users simultaneously, each of them running
dozens of different applications.
Does this sound better?
> <glossterm>Process ID</glossterm>
> <acronym>PID</acronym>
> <glossdef>
> - <para></para>
> + <para>A unik ID every process gets to distinguish it from all other
> + processes.</para>
Typo: s/unik/unique/. ID cannot be used as an explanation of ID. We
should probably rewrite this as:
Process ID (identifier). &os; is a multiprocessing operating
system. A lot of programs might be running "at the same time".
Different programs or even the same program can be loaded
multiple times. The kernel of &os; uses a unique process
identifier (PID) to distinguish between each running program
instance.
> <glossterm>Request For Comments</glossterm>
> <acronym>RFC</acronym>
> <glossdef>
> - <para></para>
> + <para>A set of documents defining internet standards, protocols etc.
> + Can be found here: <ulink url="http://www.rfc-editor.org/">RFC-editor
> + </ulink>. Also used if someone has suggestions on something and wants
> + feedback.</para>
I don't like the way two different descriptions of the "RFC" acronym
blend together. We definitely want to keep them separate; probably in
different paragraphs.
Regards,
- Giorgos
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040817114201.GC6960>