From dd581bd656a10e51b22ff7a7c2d6b55fb6c7d90a Mon Sep 17 00:00:00 2001 From: Darrell Anderson Date: Sun, 5 Oct 2014 10:50:02 -0500 Subject: Move Tutorials from tdebase. Add docbook & markup tutorials. Tutorials need editing and updating. Thus the default configuration is -DBUILD_TUTORIALS=OFF. --- doc/tutorials/styleguide/CMakeLists.txt | 9 + doc/tutorials/styleguide/Makefile.am | 3 + doc/tutorials/styleguide/index.docbook | 466 ++++++++++++++++++++++++++++++++ 3 files changed, 478 insertions(+) create mode 100644 doc/tutorials/styleguide/CMakeLists.txt create mode 100644 doc/tutorials/styleguide/Makefile.am create mode 100644 doc/tutorials/styleguide/index.docbook (limited to 'doc/tutorials/styleguide') diff --git a/doc/tutorials/styleguide/CMakeLists.txt b/doc/tutorials/styleguide/CMakeLists.txt new file mode 100644 index 0000000..396682f --- /dev/null +++ b/doc/tutorials/styleguide/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION khelpcenter/styleguide ) diff --git a/doc/tutorials/styleguide/Makefile.am b/doc/tutorials/styleguide/Makefile.am new file mode 100644 index 0000000..4169155 --- /dev/null +++ b/doc/tutorials/styleguide/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/tutorials/styleguide/index.docbook b/doc/tutorials/styleguide/index.docbook new file mode 100644 index 0000000..8c94356 --- /dev/null +++ b/doc/tutorials/styleguide/index.docbook @@ -0,0 +1,466 @@ + +The &kde; Documentation Team'> + + +]> + + + + +The &tde; Style Guide + + +&kde-authors; +&tde-authors; + + + +2002 +The KDE e.V. + + +&tde-copyright-date; +&tde-team; + + +&FDLNotice; + +&tde-release-date; +&tde-release-version; + + + +A reference guide to &tde; style standards for writing documentation. +Please report any errors or omissions to +trinity-devel@lists.pearsoncomputing.net. + + + + +TDE +Docbook +Documentation +Authors + + + + + +Introduction + +The purpose of writing documentation for the &tde; Project, is +to create for all the users, a complete, well organized set of +documentation for each and every component of the &tde; project. In +order to achieve this goal, we have drafted the following guide to +help. + +This document is very new, and at the moment, very +sparse. + +If you have comments or additions, please do not hesitate to +suggest them on the kde-doc-english@kde.org mailing list. + +In the meantime, here are some short notes based on content that +was previously on the &tde; +i18n website. + + + + +Consistency + + +Dates and Revision Numbers + +While it may seem like a minor issue, and a minor part of your +document, it is very important that the following guidelines are +adhered to: + + + +All dates which are part of the text of your document +should be spelled out &ie; March 2, 2000 +This is the only way to be sure that 03/02/2000 +is interpreted correctly in all languages, and by all readers. +Exception: in the date tag, dates +should be in the YYYY-MM-DD format. + + + +All information included between the releaseinfo and releaseinfo should match the release number +of the application. + + + + + +Screenshot Consistency + +To create consistent screenshots, use an environment where all requirements can +be configured without interfering with your normal production environment. One option +is a virtual machine. Another option is creating at least two themes. One theme is the +normal everyday theme for production. The other theme is for handbook screenshots. +Toggle between the two themes as necessary. A third option is a separate user +account configured as required. + +To strive for a look of consistency with screenshots, please abide by the +following requirements. + + + + +No personal information. That includes login names. Be careful when including +window decorations because the title bar could include such information. Use a testing +account or a virtual machine when such information cannot be avoided. + + +Use &ksnapshot;. Normally use the Window Under Cursor option. Use the + &ksnapshot; Handbook to learn more. + + +Using the &ksnapshot; Include window decorations option is not +required and not forbidden. Just ensure the decorations to do not interfere with the +purpose of the screenshot. + + +PNG images only. + + +Window decorations: KDE2, Keramik, or Plastik. + + +Widget style: KDE Classic, Keramik, or Plastik. + + +In &kcontrol;->Style, enable Show icons on buttons. + + +Colors: TDE defaults. + + +Background: No wallpaper, no gradients. + + + + + + + +Other Consistency Issues + + + +Please submit only plain ASCII text, or +Docbook &XML;. Anything else will be returned to you. (Docbook &XML; is +preferred.) + + +Make sure you first read, and follow, the documentation template +provided. You can find this in the source folder for &tde;. Simply +point a browser to tdelibs/doc/kdoctools/template.docbook +If there is existing documentation (from the developer, or +from &tde; 1.x or 2.x), then use that as a base to work from, but it +needs to conform to the layout from the documentation +template. + + +Spell things according to Standard American spelling, except for +proper names, places, &etc; + + +Make sure to set your spell checker to US English. Make sure you +use your spell checker. + + +If there is a non-English word, which is used in an English +sentence, be sure to spell this correctly, using appropriate accent +marks, and any special characters. Use the &kcharselect; application +if you don't have the correct keys on your keyboard. + + +Abbreviations should be capitalized, unless they are +specifically intended to not be capitalized. (&ie; is a good +example). + + +Punctuation within numbers should be Americanized: +10,000.00 + + +It is more legible to use written numbers where the number has +no technical value, ⪚ There are three buttons on the +dialog. In this context 3 is not technically +significant. Numbers with technical significance should be written as +figures. (&ie; a 10 MB file, not a ten MB +file.) + + +Spell check and proofread your work before you send it in. Or +even better, have someone else read it over. Spell checking programs +won't catch incorrect words such as using their for +there. + + + + + + + +Writing Well + +Some things to think about when writing documentation + +How many times have you attempted to read a man page, and given +up in frustration — all the facts are there, but the writing is +too dry and technical for you to make sense of them? We want to avoid +this with the documentation you're writing. + +It's difficult to avoid the very dry, choppy style we're all too +familiar with, but do try to make the writing flow and keep it +user-friendly. Try to be as friendly as you can +manage without being patronizing, and without sacrificing clarity or +detail. + + Things you should consider: + + + + +Make sure you explain all aspects of the interface, and that you +don't leave out any command line options available. + + + +It's important to keep a logical progression of difficulty. Keep +the first few pages of the document simple, and accessible to users +who have never seen the application before. More technical information +should appear towards the end of the document. + + + +Be sure to write to the level of the intended reader. By this we +mean, a Samba control module has a very different user base than a +user of a game, and the manuals should reflect this. Don't insult the +Samba networker's intelligence, and don't assume knowledge for the +gamer that might not be there. + + + +It is highly encouraged to use screenshots, pictures of action +buttons, &etc; These are &GUI; applications, and a picture can be worth a +thousand words. + + + +Please define computer abbreviations, unless they are well +understood by all computer users (There's no need to define +RAM, PC, &etc;). + +For example, If you are going to use +PPP (Point to Point Protocol), +then...... Define it only once though, in this example you +could now use PPP without explanation for the rest +of the document. + +The first time you introduce the word you should use firstterm or consider setting up a glossary +and using glossentry. + + + +Remember the small things: If it's dockable, explain how to do +that. Don't forget to mention where it installs itself in the K +menu. If there are any environment settings required, and if they must +be set manually, explain how to do that - if they're set +automatically, they still need to be documented. + + + +Write something you would be happy to read as a user who doesn't +know how the application works. Perhaps if you have a friend or family +member who isn't familiar with the application you're writing about, +have them work through using it, with your documentation as a +guide. + + + + + + +Other general tips and hints for good writing + +A good way to catch simple errors is to read the text out loud, +or have someone else read it to you. Passages that don't +flow or have obviously awkward construction of the type +you may miss on the screen, will usually become blindingly obvious +when you hear them. This is especially the case with detecting really +long sentences, as you will run out of breath and turn blue. + +Be concise, be specific, and be direct. Choose your words +carefully, and be certain you know the exact meaning of every word +you use. Is it the right word? Use a dictionary, and find out. + +Use complete sentences. Not fragments. Like these ones. + +While talking about sentences: + + +Avoid run on sentences, sentences that cover several different +subjects, or sentences that could be broken up into several sentences; +avoid sentences that can fill a whole paragraph all by themselves and +that are really long, like this one, which is all of the above. + + + +Use a comma before and in compound sentences, ⪚ +Use the left mouse button to select and copy text, and the +middle mouse button to paste it. + + +Keep to logical sentence order. +For example, &konqueror; is a web browser with the +ability to browse file systems and it includes a javascript +interpreter. (Do you see why this is awkward?) + + +Try not to use the same word several times in the same sentence. +An exception to this, is an application command or technical word, +where this repetition is necessary, and improves clarity. + + +Do not start sentences with any of and, +so, but, because, or +however. + + +Try to avoid contractions, rather spell out both words; ⪚, +it is rather than it's; can +not rather than can't + + +There is no need to worry about simple text formatting such as +leaving two spaces after punctuation or indenting paragraphs. This is +all handled by Docbook &XML; and the XSLT +stylesheets in use. + + + +Remember, we have also an active proofreading team, and there is +always someone to help you with grammar, so just +write and have fun! + + + + +Resources + + +General Purpose Websites + +A few sites you may find worth bookmarking, or at least +visiting. + + +Dictionary Sites + + + +Merriam Webster +Online + + +Dictionary.com + + + + + + +Thesaurus Sites + + + +Merriam-Webster have a +thesaurus as well as a dictionary + + +Roget's +Thesaurus + + + + + + +Style Guides and Other Resources + + + +Strunk & +White is the base style guide for many newspapers and press +galleries. If you want to look up a grammar or usage question, this is +the place to go. + + +The alt.usage.english newsgroup. +If you'd like every sentence chewed over, dissected, and then +rewritten several conflicting ways, or some great advice about bacon, +you'll find both here. Many real live editors and authors hang out +here, and they do know their stuff. Just make sure you read all ten +or so FAQ's before asking a question. + + +Other possibly useful sites + + +The Wired + Style Guide Bookmarks section + + + +http://www2.rscc.cc.tn.us/~jordan_jj/OWL/Clutter.html +If you tend to write very wordy sentences, here's a page with some +help for you. Includes a useful table of ways to rewrite common +mistakes. + + +http://owl.english.purdue.edu/Files/116.html + is a page about how to make sentences flow +better + + + + + + + + + + + +Credits and Licenses + +The &tde; Documentation Style Guide + + +Copyright 2002, Lauri Watts, Mike McBride, Eric Bischoff, +Frederik Fouvry. +Copyright &tde-copyright-date;, &tde-authors;. + +&underFDL; + + + + + + -- cgit v1.2.1