diff --git a/Documentation/Index.rst b/Documentation/Index.rst index a8e37f8e..d6be5043 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -113,7 +113,6 @@ What's new in this guide? :hidden: :caption: HOWTOS - WritingContent/Index WritingDocForExtension/Index WritingDocsOfficial/Index RenderingDocs/Index diff --git a/Documentation/WritingContent/Index.rst b/Documentation/WritingContent/Index.rst deleted file mode 100644 index 1ac55744..00000000 --- a/Documentation/WritingContent/Index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. _writing-content: - -========================= -How to write good content -========================= - - -* Divio: `"The documentation system" `__, based on - Daniele Procida's 2017 blog post, "What nobody tells you about documentation". - It establishes four distinct categories of documentation content. - -.. figure:: /Images/content-types.png - :class: with-shadow - - Overview of content types, taken from Daniele Procida - -**Table of contents** - -.. toctree:: - :titlesonly: - - WritingContentTips - Tutorial - Resources - - -.. todo:: finalize Guide.rst - - diff --git a/Documentation/WritingContent/Resources.rst b/Documentation/WritingContent/Resources.rst deleted file mode 100644 index 8c2c10d5..00000000 --- a/Documentation/WritingContent/Resources.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: Writing; Resources -.. _resources: - -================= -Writing Resources -================= - -Online Resources -================ - -documentation writing: - -* Daniele Procida: `"What nobody tells you about documentation `__ - (May 19, 2017) - A very good blogpost about different kind of manuals. - -general writing tips: - -* `"8 Tips for Better Readability" by Roby Collinge - `__ - is a very good resource. However, some of the tips do not concern you as - a writer. They are only relevant for theme development. As a writer, skip - right down to tip 5. -* `Neil Patel: How to Write With Clarity: 9 Tips for Simplifying Your Message `__ - This is also not an article that is specific to documentation, but the tips - are very good and general, especially for writing in clarity in mind. - - -.. pull-quote:: - - Clarity means making your content easy to understand. - - -- Neil Patel - - -* `Strunk & White: "The Elements of Style `__ - is a classic. Many principles still apply. - -Videos -====== - -* `Daniele Procida: What nobody tells you about documentation `__ - - -Programs -======== - -* Google Season of Docs diff --git a/Documentation/WritingContent/Tutorial.rst b/Documentation/WritingContent/Tutorial.rst deleted file mode 100644 index 6f9acf30..00000000 --- a/Documentation/WritingContent/Tutorial.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: pair: Writing; Tutorials -.. todo:: Add information about writing a tutorial - -.. _writing-tutorial: - -================== -Writing a tutorial -================== - - -Text used so far in the first section of TYPO3 tutorials: - -*"This document is a tutorial. Tutorials are designed to be step-by-step instructions -specifically created to walk a beginner through a particular task from beginning to -end. To facilitate effective learning, tutorials provide examples to illustrate -the subjects they cover. In addition, tutorials provide guidance on how to avoid -common pitfalls and highlight key concepts that should be remembered for future reference."* - -From looking at the literature mentioned below we should consider the following key points: - -* a tutorial is a lesson, learning oriented, showing steps to complete something, making the reader more knowledgable - -* the reader should achieve something meaningful and experience success, find it doable and enjoyable, enhance competence, gain confidence, and wants to do it again. - -* concentrate on practical knowledge, not theoretical knowledge. Learn a new craft or skill, concentrate on learning by by doing - -Guidelines: - -* allow the user to learn by doing, - -* go from simple to complex - -* Get the user started - -* it’s ok to show the steps the beginner understands best. “best practice” may be something different. How an experienced user would do it may be something different. - -* The goal is to get the reader started, not to get them to a final destination. - -* Make sure that your tutorial works! - -* inspire the beginner’s confidence: in the software, in the tutorial, in the tutor and, of course, in their own ability to achieve what’s being asked of them. - -* Ensure the user sees results immediately - -* The conclusion of each section of a tutorial, or the tutorial as a whole, must be a meaningful accomplishment. - -* Your tutorial must be reliably repeatable. - -* Focus on concrete steps, not abstract concepts. The temptation to introduce abstraction is huge: resist! - -* Provide the minimum necessary explanation - -* Focus only on the steps the user needs to take - -Literature -========== - -* `Ubuntu: How to write a tutorial `__ -* Daniele Procida: `"What nobody tells you about documentation `__ - (May 19, 2017) - A very good blogpost about different kind of manuals. diff --git a/Documentation/WritingContent/WritingContentTips.rst b/Documentation/WritingContent/WritingContentTips.rst deleted file mode 100644 index 837c2cdb..00000000 --- a/Documentation/WritingContent/WritingContentTips.rst +++ /dev/null @@ -1,171 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: rst -.. index:: Writing; Content -.. _write-good-content: - -============================= -Tips for writing good content -============================= - - -.. index:: Writing; Readability - -How people read on the web -========================== - -People read differently on the web than they read print media. - -.. pull-quote:: - - "On the web, however, most of us scan information, jumping - from one point of interest to the next, hoping to trip over - some relevant facts. In fact, according to a study by the Norman - Nielsen Group, your visitors will only ready between 20 and 28% - of the words on your site." - - -- `"8 Tips for Better Readability" by Roby Collinge `__ - -This information is not specific to online documentation, it is about -information on the web in general. Nonetheless, we should consider -that information about reading on the Web at least partly -applies to reading online documentation as well. - -So: - -* Readers on the web often do not read, they scan (skim). -* Additionally, they often do not read entire manuals, they google for - the information they are looking for and start reading there. - - -.. index:: Writing; Online - -Tip 1: Write for online reading -=============================== - -* Make it easier for the reader who has not read previous pages. -* Make sure, the title is clear. -* Text with good formatting is easier to scan (see the next two - tips) - - -Tip 2: Use paragraphs -===================== - -In any case, avoid long "walls of text". Give the eye something to cling to. - -Tip 3: Use subheaders -===================== - -Look at `this page `__ - -Imagine removing all the subheaders and then reading it. - - -Tip 4: Think about your audience -================================ - -What is the typical target audience of your text? -Put yourself in the shoes of your readers while writing. -Find someone from your target audience to read your text and -give feedback. - - -Tip 5: Use a consistent and clear vocabulary -============================================ - -Use specific (not ambiguous) language. - - -Tip 6: Write simple, short sentences -==================================== - -Keep the text as short as possible. Edit out anything that can be omitted -without loss: - -.. pull-quote:: - - "Vigorous writing is concise. A sentence should contain no unnecessary words, a - paragraph no unnecessary sentences, for the same reason that a drawing should have no - unnecessary lines and a machine no unnecessary parts." - - -- `Strunk & White: "The Elements of Style `__ - - -Tip 7: Use a spellchecker -========================== - -.. hint:: - - Use a spellchecker that also points out grammar mistakes and gives - recommendations for style improvements. Try out this - `free online check `__ by - Grammarly. - - -Tip 8: Use Stack Overflow to learn -================================== - -Yes, `Stack Overflow `__ can be a good teacher. Or, we -should add, its users are. - -You may notice, there are some good -answers on StackOverflow, ideally formatted for readability, very well written -and structured. If you have not signed up for StackOverflow yet, do it now -and start writing questions and / or answers. - -Advanced Stack Overflow users `often use number or -unnumbered lists `__ and other formatting -elements. - -Of course, it is better to keep the text on Stack Overflow as short as possible, -but if the text is longer than a paragraph, lists help to structure the text -and make it more readable. - -Additionally, some users are very good at explaining things. - -See how this `highly voted answer by Mysticial on branch prediction -`__ uses a railroad junction -analogy. - -You can use the advanced search to search for `highly voted answers -`__, -but note that number of votes correlates with a number of factors. Quality is not always -the decisive factor (it also depends on whether the information is relevant for -a high number of users). - - -Tip 9: Read other documentation -=============================== - -* Ask yourself questions: What works for you, what doesn't? - -Here are some tips: - -* `Docker `__ -* Google Developer: `Get Started With Analyzing Runtime Performance `__ -* `use TYPO3 blog `__ - - -Tip 10: Read your own content -============================= - -When you write new content, finish it, **wait a few days**, and then read it again! - - -.. _write-good-content-resources: - -Additional Resources -==================== - -* Daniele Procida: `"What nobody tells you about documentation `__ - (May 19, 2017) - A very good blogpost about different kind of manuals. -* `How to fix the 7 most common glitches in technical writing `_ -* `"8 Tips for Better Readability" by Roby Collinge - `__ - is a very good resource. However, some of the tips do not concern you as - a writer. They are only relevant for theme development. As a writer, skip - right down to tip 5. -* `Strunk & White: "The Elements of Style `__ - is a classic. Many principles still apply. - -You can find more in the :ref:`resources` section.