Content review needed (October 1, 2008) jdd

Wiki Author's Guide - jdd

Revision History

Revision 0.1 2008-09-28 jdd
Wiki use version of the author guide

The LDP Author guide is a very complete guide about about writing HOWTOs. Part of it is devoted to the use of docbook. We hope to be able to free the authors from this docbook work by the way of the wiki. This is work in progress (October 2008). However, we still need to have a docbook source and structured documents. This is not obvious, specially on a wiki. We will try to help you give this result. This HOWTO is only about the use of the wiki, reading the complete author guide is still very valuable for new authors.

Beginning

Licence

      Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License,
      Version 1.2 or any later version published by the Free Software
      Foundation; with no Invariant Sections, no Front-Cover Texts and
      no Back-Cover Texts.  A copy of the license is included in the
      section entitled "GNU Free Documentation License".

GNU Free Documentation License

Feedback

Send feedback to discuss AT en.tldp.org. Please reference the title of your document in your email. Please note: you must be subscribed in order to send email to the list.

Authoring TLDP Documents

Summary of The LDP Process

The following section outlines the process of creating and/or maintaining a document for the Linux Documentation Project on the LDP wiki. This section includes all steps--some of which may not be relevant to your specific document.

  1. Choose a licence. We hope you will choose the LDP default licence, because this makes our work easier, but you can as well choose any of the licences listed here.

    • If you want an other licence for a reason, please discuss it on the discuss list.
  2. Write your document. If your document has not yet been written, please be sure to email the discuss list before you start writing.
  3. You are the maintainer of your document as well as the author. A document in a wiki can be edited by anybody. Most edits are for fixing typos or small changes, but some may be wrong or malevolent. We will address this below, but as a summary always report on the discuss list any problem. If you are a real expert on the subject and the subject is difficult, you can ask to be the only one to have writing rights.
  4. Don't forget to write in your document a way to contact you, valuable for any time as long as your document is usefull. You can write e-mails and URLs' in human reading form only if you want.
  5. You can, and are encouraged to, flag your document with admonitions, to report to the reader the status of the document. Do not use admonitions to markup your document content, but only to communicate with the other members/authors/visitors. See below for the admonitions use.

  6. Submit your document for technical, language and metadata reviews. Do this by emailing the URL of your document to <discuss AT en.tldp.org>. In the subject line be sure to give the title of the document. In the body of the email say that you are ready for the review process. Outline any additional reviews your document may have already received. Flag your document with the relevant admonition.

  7. Once your document has been reviewed at your pleasure, write in the wiki comment line (the one just under the edit box window) - it will be automatically added to the final document. Flag it with the relevant admonition and announce this to the discuss list. The document will be made read only for a short time, until it can be moved to the static mirrored part of the LDP web site, AKA published. Then a new editing session can begin. You can also save it as docbook ("Render as docbook") and submit it through the submit list.

  8. Revisions have only to be made when necessary, not at regular dates, however it may be good to sometime make a small change to update the wiki history and show you are still managing your doc. Some docs need frequent udating, some other nearly never, but it's good to know it's still up to date. Look at the "info" tag to see who/how/when visitors have modified your document.

WRITE on the wiki

Don't be afraid

The wiki markup, yet an other wiki!, the length of this HOWTO, the pressure of the public, all this shouldn't prevent you from writing your document.

Do not bother of english quality, orthograph, not even about wiki markup. The wiki magic is than it's very easy for other people to fix what you couldn't.

So, concentrate on the subject you know the better and write the most exact technical document. As soon as you think your document is technically correct, announce it on the discuss list and wait :-).

The only really important thing to know is that you have to let a blank line between two paragraphs. Apart this nothing is mandatory.

Note
of course if you can write a perfectly good doc, with no error at all, it's even better!

Fill your own wiki page

As soon as you have subscribed the wiki, you own a personal page, accessible from the link found in the top right corner of every page once logged in.

Be aware that this pages have the same reading and writing permission than any other. It's of bad practice to write on the others personal page, but anybody can read it.

You can organize your work from there. First present yourself to the others, summarize very shortly what you want to do.

Then create a new page here, going to text edit box and writing  *[[Name of your HOWTO]] (you must have a blank at the beginning of the line, before the "*", this begin a bullet list, in the hope you will write many HOWTOs :-).

Fill the box on top of the edit window, answering the question. This is to fight the spam.

Save.

The first thing you have to know now is that anytime you preview your work in the edit window, this work is saved and you can retrieve it should you have a problem.

You should see your HOWTO name with a preceding interrogation mark "?"

Clic on it and you are presented a template menu. You can begin writing.

Using templates

When one create a new page in MoiMoin wiki, the LDP wiki engine, he is presented with a choice of templates and similar documents.

As of October 2008, we are still in a very preliminary state and true templates have yet to be written. However there is one for HOWTO that is very rough but gives a starting point.

You also have as a choice some examples of similar documents (based on the name), you can also choose one.

You can also choose to start with a blank page.

In the edit page, on the right of the edit window, you have a very short summary of the wiki help and links to other pages. You have also links to help pages from ordinary wiki pages, on the tag upper line.

The MoiMoin help is not the better part of this wiki. We will surely have sometime to enhance it. Right now, we have a page on our wiki with help on some subject interesting to us.

Tagging your document with admonitions

Admonitions, in the MoinMoin language are tags like this one:

Don't overuse admonitions

Admonitions should be used with care. A page riddled with admonitions will look restless and will be harder to follow then a page where admonitions are used sparingly.

corresponding to this code in the wiki page:

{{{#!wiki caution
'''Don't overuse admonitions'''

Admonitions should be used with care. A page riddled with admonitions will look restless and will be harder to follow then a page where admonitions are used sparingly.
}}}

See MoinMoin help on admonitions and Ldp admonitions page.

Don't use admonitions to enhance your text. Use them as a flag to the other members of the LDP: warning about document completion, kind of licence used, "don't edit!!" or "work in progress" to prevent others from trying to help you on a too preliminary work. LDP will create his own set of admonitions soon (writen October 1, 2008).

Structuring your doc

The wiki allow writing nearly anything in any order. This don't gives coherent documents. We have to be smart.

For example, use title, but do hierarchical use. = First level title = is for chapters and should be followed immediately by == Second level titles == with no text in between.

Use at will the wiki markup for lists, numbered or not. Use tables.

Using subpages

Sub pages are created using the [[/pagename]] syntax in the main page. They can be seen as chapters within a book.

Be aware that subpages are not always easy to manage for the reader (for example, it makes it very difficult to print the hole document). HOWTOs should be quite short documents and so avoid sub pages. Guides are more book oriented and can allow sub pages. Try not to have more than one subpage level (no sub page of a subpage).

It's always easy to move part of the document from the original to a sub page afterward, try to keep all the document as one page at first.

Usually, LDP scripts allow several variants of displaying the document: finally your HOWTO will be available as text, html single page, html multiple pages... so don't spend too much time on sub pages, look at the wiki as the document source, not as the final version the user will see.

Only users needing a very uptodate documentation should come directly to the wiki (at risk of having a non finished one).

Using categories

Categories is a very powerfull to organize the HOWTOs in the wiki, by building several indexes. As of october 2008, we don't have yet a category policy

Acknowledgments and Thanks

Here, version numbers as those of the LDP original Author guide

Version 1 - Version 3

Thanks to everyone that gave comments as I was writing this. This includes David Lawyer, Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig and other members of the <discuss AT en.tldp.org> list. Some sections I got from the HOWTO Index and the sgmltools documentation. The sections on network access to CVS was partially written by Sergiusz Pawlowicz (<ser AT metalab.unc.edu>). Sections on DocBook were written by Jorge Godoy (<godoy AT conectiva.com>). A great deal of thanks to both of them for their help.

Version 4

Thanks to Tabatha Marshall and Machtelt Garrels (Tille) for making sure I actually finished the document. Thanks to my reviewers: Charles Curley, Martin Brown and Tille; and to Saqib Ali for his on-line transformation and validation tools. I have also incorporated a number of useful emails from the LDP mailing lists. The original authors are credited within the document. Special personal thank yous are extended to Steve Champeon for getting me interested in markup languages and for being a wonderful mentor; and to my partner, Graig Kent, for being outrageously supportive. [EJH]

WikiAuthorGuide (last edited 2010-02-14 17:58:27 by MichaelMol)