2:26 p.m.
We definitely need more writers and content. Here is a summary of my
recruiting spiel, and I encourage all of you to look for opportunities
to recruit new writers:
* When someone complains about the docs, ask if they are interesting in
helping to make them better.
* When someone posts any kind of doc, ask if they are interested in
making it a Fedora doc (such as Rahul just did on f-devel-l).
* When someone expresses a desire to help a particular project or just
open source in general, use the arguments below to see if they might
like being a doc writer.
Where to look:
* The LUG you are a member of and related technical groups (IEEE, SANS,
etc.)
* IRC and other help forums.
* Within existing upstream projects, e.g. GNOME, Samba, etc.
In the latter case, a person might be able to get a document into Fedora
that wouldn't fit or be accepted in an upstream project.
Here is a modified spiel I sent out recently. It's a bit long, but it
embodies all the ideas I've thought of. I've used this same kind of
content in IRC to recruit folks.
##
The Fedora Project is looking for more writers.
You don't need to be a great writer. That's why we have editors.
Look upon it as a chance to improve your writing skills while
contributing to the Fedora community.
If this intrigues you at all, please read on.
Maybe you've wanted to be involved with Fedora but don't know a way.
Or you want to expand your involvement. Consider writing or editing
for the Fedora Docs Project (FDP):
* Have closer contact with your favorite developers and projects.
* Become or further expand into being a subject matter expert for
your favorite topics.[1]
* Gain reputation within the community.
* Learn to be a better writer, editor, and technical reviewer.
What might you write about?
* Be the release notes subject expert.
* Installation or configuration of any software or hardware under
Fedora Core, including any of the sub-projects such as Fedora
Extras, Fedora Directory Server, and so forth.
* General or security best practices, even abstracted from the OS
but still relevant to Fedora Core.
* Whatever interests you.
What is there to worry about?
"The toolchain is hard."
If you don't know DocBook, it's definitely time for you to learn.
Meanwhile, project members have volunteered to help anyone get their
document converted into DocBook. From there, you can teach yourself
as you continue writing and maintaining.
We are using the Wiki at http://www.fedoraproject.org/ and remain
open to further toolchain/publishing considerations. Heck, if you
want to get fedoraproject.org to host a blog that to publish
tips-n-tricks, that would be a great Fedora documentation effort.
"The amount of content is a lot to write and maintain."
The FDP is geared to small how-to and tutorial documentation. If
you know your subject area, you can likely write a usable draft that
is 80% complete content within a few hours. Give it a try.
You can contribute to a larger guide, such as a chapter or even a
section. This is currently true for the release notes, and may be
how the Fedora Installation Guide is handled in the future.
If you are writing about what you know and alrady use, then the odds
are that you will be using it in the future and can easily maintain
a document on the subject. This is the difference between Fedora
docs and the kind of documentation that Red Hat Enterprise Linux
does: massive guides are hard to maintain, while small tutorials
and how-to docs can be practically painless to maintain.
"I hate writing."
We need technical editors, especially if more writers start joining.
We may need your help in an area you know about already, in terms of
the toolchain, automation, CVS management, project management and so
forth.
Since effective communication is a part of all of our lives, perhaps
this is an opportunity for you to get free editing and writing
advice. This is especially helpful for non-native writers who would
like to improve their English writing skills.
Interested? Drop a note to fedora-docs-list(a)redhat.com and tell us
whatever you want.
[1] To see what this has done for one Fedora wirter, google for
"selinux" and see the second full return. The Fedora SELinux FAQ has
a lot of googlejuice.
## 30 ##
^^^^^^^^ -- This is an old newspaper usage for "that's all, stop setting
type."
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
6:46 p.m.
Another point someone just made to me, we want to include writers and
editors of all technical levels.
Since our docs need to reach audiences from the newest user to the
oldest hacker, we should have writers who fill those descriptions to be
successful.
So, added points:
* If you want to learn more about the technology, there is nothing quite
like documenting it to learn something thoroughly.
* Your technical level doesn't matter, since we need writers at all
levels to create docs for users at all levels.
* If you are interested in technical writing, documenting Fedora is a
great way to gain experience.
- Karsten
On Wed, 2005-03-30 at 12:26 -0800, Karsten Wade wrote:
We definitely need more writers and content. Here is a summary of
my
recruiting spiel, and I encourage all of you to look for opportunities
to recruit new writers:
* When someone complains about the docs, ask if they are interesting in
helping to make them better.
* When someone posts any kind of doc, ask if they are interested in
making it a Fedora doc (such as Rahul just did on f-devel-l).
* When someone expresses a desire to help a particular project or just
open source in general, use the arguments below to see if they might
like being a doc writer.
Where to look:
* The LUG you are a member of and related technical groups (IEEE, SANS,
etc.)
* IRC and other help forums.
* Within existing upstream projects, e.g. GNOME, Samba, etc.
In the latter case, a person might be able to get a document into Fedora
that wouldn't fit or be accepted in an upstream project.
Here is a modified spiel I sent out recently. It's a bit long, but it
embodies all the ideas I've thought of. I've used this same kind of
content in IRC to recruit folks.
##
The Fedora Project is looking for more writers.
You don't need to be a great writer. That's why we have editors.
Look upon it as a chance to improve your writing skills while
contributing to the Fedora community.
If this intrigues you at all, please read on.
Maybe you've wanted to be involved with Fedora but don't know a way.
Or you want to expand your involvement. Consider writing or editing
for the Fedora Docs Project (FDP):
* Have closer contact with your favorite developers and projects.
* Become or further expand into being a subject matter expert for
your favorite topics.[1]
* Gain reputation within the community.
* Learn to be a better writer, editor, and technical reviewer.
What might you write about?
* Be the release notes subject expert.
* Installation or configuration of any software or hardware under
Fedora Core, including any of the sub-projects such as Fedora
Extras, Fedora Directory Server, and so forth.
* General or security best practices, even abstracted from the OS
but still relevant to Fedora Core.
* Whatever interests you.
What is there to worry about?
"The toolchain is hard."
If you don't know DocBook, it's definitely time for you to learn.
Meanwhile, project members have volunteered to help anyone get their
document converted into DocBook. From there, you can teach yourself
as you continue writing and maintaining.
We are using the Wiki at http://www.fedoraproject.org/ and remain
open to further toolchain/publishing considerations. Heck, if you
want to get fedoraproject.org to host a blog that to publish
tips-n-tricks, that would be a great Fedora documentation effort.
"The amount of content is a lot to write and maintain."
The FDP is geared to small how-to and tutorial documentation. If
you know your subject area, you can likely write a usable draft that
is 80% complete content within a few hours. Give it a try.
You can contribute to a larger guide, such as a chapter or even a
section. This is currently true for the release notes, and may be
how the Fedora Installation Guide is handled in the future.
If you are writing about what you know and alrady use, then the odds
are that you will be using it in the future and can easily maintain
a document on the subject. This is the difference between Fedora
docs and the kind of documentation that Red Hat Enterprise Linux
does: massive guides are hard to maintain, while small tutorials
and how-to docs can be practically painless to maintain.
"I hate writing."
We need technical editors, especially if more writers start joining.
We may need your help in an area you know about already, in terms of
the toolchain, automation, CVS management, project management and so
forth.
Since effective communication is a part of all of our lives, perhaps
this is an opportunity for you to get free editing and writing
advice. This is especially helpful for non-native writers who would
like to improve their English writing skills.
Interested? Drop a note to fedora-docs-list(a)redhat.com and tell us
whatever you want.
[1] To see what this has done for one Fedora wirter, google for
"selinux" and see the second full return. The Fedora SELinux FAQ has
a lot of googlejuice.
## 30 ##
^^^^^^^^ -- This is an old newspaper usage for "that's all, stop setting
type."
--
fedora-docs-list mailing list
fedora-docs-list(a)redhat.com
To unsubscribe:
http://www.redhat.com/mailman/listinfo/fedora-docs-list
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
10:51 a.m.
Hi, this sounds like something for me to pipe up on. I've recently
joined this list because I'm very keen to see improvements in docs for
linux generally. Here are some of my thoughts.
- it's wrong to think that newbies can't write docs, they can best write
docs for other newbies about things they've just come to grips with.
this means that docs need to be (at least) as easy to edit as wikipedia.
Another good example that springs to mind is the php manual.
http://www.php.net/manual/en/configuration.php
- the absence of docs written for non-nerd windows users on how to get
started in linux is horrendous. All the things I've seen either
oversimplify or are written for command line types.
- the fact that so many distros have their own completely seperate docs
for the *very same programs* is absurd. ubuntu springs to mind - great
project, but a lot of reinventing the wheel as far as much of their docs
go.
In the course of writing this it strikes me that there are three main
levels of doc-writers. It *must not* be a locked and/or techhead
oriented issue.
* Top level: Full editorial power - responsible for maintaining a
logical structure for the docs.
* Middle level: 'Node editors' - edit any given page of the docs, but
not the logical structure.
* Bottom level: Joe public - able to add comments to a page. Comments
may or may not be included in 'official doc releases' but always give
ideas for those editing the docs.
If anyone thinks any of this is worth saying/ hearing/ advocating -
let's talk about it... :-)
Duncan
2:35 a.m.
On Thu, 2005-03-31 at 18:51 +0200, Duncan Lithgow wrote:
Hi, this sounds like something for me to pipe up on. I've
recently
joined this list because I'm very keen to see improvements in docs for
linux generally. Here are some of my thoughts.
- it's wrong to think that newbies can't write docs, they can best write
docs for other newbies about things they've just come to grips with.
this means that docs need to be (at least) as easy to edit as wikipedia.
Another good example that springs to mind is the php manual.
http://www.php.net/manual/en/configuration.php
Yes, definitely the newbie factor was an oversight in my original post.
There was a follow-up a few hours later in support of what you are
saying.
- the absence of docs written for non-nerd windows users on how to
get
started in linux is horrendous. All the things I've seen either
oversimplify or are written for command line types.
I agree that Fedora docs needs to stretch from the newest to the oldest
user.
- the fact that so many distros have their own completely seperate
docs
for the *very same programs* is absurd. ubuntu springs to mind - great
project, but a lot of reinventing the wheel as far as much of their docs
go.
This is not likely to go away. Go to a bookstore and into the computer
book section, you won't find one book for each topic. Go to your
favorite distro and see how many mail clients there are.
Still, there is value in adopting upstream documentation. We could
consider that for some areas such as GNOME. I want to review it on a
case-by-case basis.
In the course of writing this it strikes me that there are three
main
levels of doc-writers. It *must not* be a locked and/or techhead
oriented issue.
* Top level: Full editorial power - responsible for maintaining a
logical structure for the docs.
* Middle level: 'Node editors' - edit any given page of the docs, but
not the logical structure.
* Bottom level: Joe public - able to add comments to a page. Comments
may or may not be included in 'official doc releases' but always give
ideas for those editing the docs.
This idea works for a Wiki pretty well.
I think there is a natural limit to how useful purely collaborative
documentation is. When it comes to an action that can destroy or make
surprise data changes, I'd like Fedora users to know they can come to a
more trusted authority. For example, I've used forum answers at
linuxquestions.org as a starting place that helps refine the search.
Rarely is the final answer to be found there.
Much of the easy and useful pieces have already been produced by the
Fedora documentation efforts. Those have a different scope than we do.
Full tutorials and how-to documentation is different from short how-to
documents. We take more time to write longer documents, but the result
is something that is well tested and useful to a wide audience. It is
something worth maintaining, instead of a collaborative posting that may
get abandoned.
One of the founding principles of the Fedora docs project was to attempt
the quality of Red Hat Linux documentation. To do this requires a more
formalized writing discipline. It's like the difference between an
article published in a magazine and a blog.
All that said, I agree that we can consider some of our content areas
and audience as being best served with collaborative docs in a Wiki.
I'd consider these on case-by-case basis.
- Karsten
--
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
6973
days inactive
6975
days old
3 comments
2 participants
participants (2)
-
Duncan Lithgow -
Karsten Wade