Differences between revisions 2 and 3
Revision 2 as of 2008-12-15 18:50:54
Size: 3521
Editor: jdd
Comment:
Revision 3 as of 2008-12-15 18:52:36
Size: 3603
Editor: jdd
Comment:
Deletions are marked like this. Additions are marked like this.
Line 8: Line 8:
== Have an idea == = Have an idea =
Line 11: Line 11:
== Have the knowledge == = Have the knowledge =
Line 18: Line 18:
== Write the document == = Write the document =
Line 23: Line 23:
== Write the final document == = Write the final document =
Line 35: Line 35:

= links =
 * http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html

Authoring a document for the LDP is a several steps process.

  • have an idea of content, problem and his solution;
  • have the knowledge to answer the problem or know where to find it;
  • be prepared to write a well organised document. This have nothing to do with the hardware support and all on pedagogy. It's the more interesting, but also the more challenging part;
  • write down the text in a reasonable amount of time and on a manageable support;
  • publish the document - this is the LDP part of the work

Have an idea

It's much easier thant most people think. If you find a man page difficult to understand, an already written HOWTO obsolete or you find yourself writing hints on configuring your favorite mail agent, you are ready to go to the second step :-)

Have the knowledge

There are two situations dealing with usefull results.

You are already an expert in some part of the Linux World, and you want to share your expertise. This may simply mean you are a student and made a white paper or a thesis about the subject and nobody else did wonder to write on the subject for some years.

Or your are a complete newbie (newcommer) on this aspect of Linux (for example setup a Kerberos server on a new computer), and you don't think the already available documentation is really friendly. As long as the document is clearly quoted, your experience is very interesting. Experts have often forgotten what they did initially. Writing down the beginners problem may be invaluable for the other beginners. Write a "Kerberos for beginners HOWTO" (just an example).

Write the document

Write a well organised document is a challenge. It's very difficult. Most of the time it mean writing it in he's mind and dream on it. When you can't sleep because the document runs in your head, get up and write it down on a paper.

Write it on a paper first, or on your favourite word processor. Chance is you will have to rewrite it often before being glad about the result.

Write the final document

You have to think that your document will not be read by your audience in the form you write it. The LDP will spread this document all over the world. There, many, many people will see it. Any of them have a different configuration. Some don't have computers at all and need paper hard copies. Some have very large screen and can see on screen news paper large documents. Some have color, but most don't, or can't print with colors.

So your document have to be is source form. The prefered source form of the LDP is Docbook, because we have scripts that can copy this source to a great number of formats. See the HOWTO page of the Web site for examples of these formats, but many people download our source format to convert it themselve in even more final formats.

If you can write directly with docbook markups, so good! But if you can't, dont worry, the LDP wiki is here to help you. Wiki markup is much more easy to write than Docbook - simply it's easy to write oddly organised documents on a wiki, so you will have to be cautious about this. But the good news is that many people will be able to help you to fix bugs in your doc.

If you can write Docbook, the LDP Author guide is a very good starting point.

The Wiki Author Guide is for those that are to use directly the wiki.

And here you will find tips and tricks for the wiki use.

links

Creating-a-Document (last edited 2009-03-15 08:27:43 by jdd)