typo3-documentation / typo3cms-guide-howtodocument

Guide "Writing Documentation" for contributors and extension authors.

Writing Documentation

This guide contains information about contributing to TYPO3 documentation, writing documentation for TYPO3 extensions and formatting with reST and Sphinx.

Repository:	https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument
Read online:	https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/

typo3cms-guide-howtodocument's Issues

Fix some formatting for indented text now styled as quote

• https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/InlineCode.html#when-to-use-literal-code

• https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CommonPitfalls/Hyperlinks.html#correct-syntax

• https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CommonPitfalls/Indents.html#common-mistake-1-incorrect-indents

• https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CommonPitfalls/InlineStyle.html

• https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CommonPitfalls/Lists.html

Add missing information about publishing an extension and making documentation available

In https://docs.typo3.org/typo3cms/HowToDocument/WritingDocForExtension/CreateFromScratch.html there are some open questions:

• what else do you have to do to publish the extension and make the documentation available

Update or delete tip of the day for triggering rendering

https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/TipOfTheDay.html#trigger-documentation-rendering-on-the-documentation-server

Find better terms for "Github method" and "git / docker method"

Update: use "Edit me on GitHub Workflow" and "Local Editing and Rendering with Docker"

---

If possible, find better terms, so people understand what it is, just by reading it, see https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/WorkflowMethods.html

"GitHub method". Alternatives

• "Online Editing with GitHub"
• "GitHub Online Method"
• "GitHub Online Workflow"
• "Edit me on GitHub Workflow"

"Git / Docker method". Alternatives:

• "Local Editing and Rendering with Docker"
• "Local Workflow with Git & Docker"

Add some more information for documenting extensions: Create links to issues

1. create a link to issues in "Related links"

Settings.cfg:

[html_theme_options]
# show link to issues in Related links
project_issues       = https://github.com/georgringer/news/issues

2. Define where issues are and make it possible to use textrole "issues" to refer to specific issue

in your .rst source files you can use the textrole issue with an issue number, see https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/InlineCode.html#use-textroles

Settings.cfg:

[extlinks]
# Link to your issues
issue = https://github.com/georgringer/news/issues/%s | Issue #

And use it in your .rst file like this:

 :issues:`11`

Use `/Includes.txt` instead of relative path?

If I remember correctly, this is now possible:

.. include /Includes.txt

instead

.. include:: ../../Includes.txt

Confirm this and document it.

Writing Documentation: Move things from the Wiki

Most things can be merged, for some it might make sense to keep the Wiki page but add a link.

• https://wiki.typo3.org/ReST_Syntax (text is well written and some of the explanations shorter and more to the point, see if this can be merged in ..)
• https://wiki.typo3.org/Documentation_images
• https://wiki.typo3.org/Editors_(reST)
• https://wiki.typo3.org/Contributing_to_the_documentation (marked for deletion)
• https://wiki.typo3.org/Alternative_Language (concerns Wiki only)
• https://wiki.typo3.org/DocTeam/Official_Documentation_Screenshots (added outdated tag)
• https://wiki.typo3.org/Rendering_reST_on_Linux

categories:

• https://wiki.typo3.org/Category:DocTeam
• https://wiki.typo3.org/Category:About_documentation

other

• this https://wiki.typo3.org/Documentation_Process_-_Problems_and_Resolutions might rather be moved to the protocols in the forge wiki: https://forge.typo3.org/projects/team-docteam/wiki

When moving please make sure to always

• add a link to new content
• always add the category Moved: [[category: Moved]]

or better: create redirect on server and remove the page (see discussion in #typo3-wiki channel on Slack)

see: https://wiki.typo3.org/WikiMigration

Update information on licenses with specific text snippet for creative commons license

https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/Licenses.html

e.g. use text from sitepackage tutorial:

License: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0), https://creativecommons.org/licenses/by-nc-sa/4.0/

Optimize and agree on image icons

This is about creating images with arrows, boxes, numbers etc. for highlighting things. See also initial issue #11: "Add guidelines for images" (closed).

Status quo

We created "Guidelines for Images" and design team supplied some sample icons.

Problems

We should further refine icons and sample images because:

• color scheme of icons clash with orange used in documentation, choose different color? (see (t3docstheme issue #110), see TYPO3-Documentation/sphinx_typo3_theme#79 (comment)
• Using flat arrows doesn't look so great - question do we need arrows, for example this images uses a drop as combination of a pointing device and a number
• placing the numbers with rounded edges next to boxes with rounded edges does not look so great or is difficult to get right, especially if the rectangle has rounded edges

todos

• decide on colors
• decide on shapes
• make sample shapes easier to use (e.g. import into graphics tool) - it is possible to create one SVG including all images and import them for example in Inkscape - https://softwarerecs.stackexchange.com/questions/74442/workflow-and-tools-to-augment-screenshots-with-custom-arrows-numbers-boxes-etc/74602#74602

Add conventions for commit messages

Document the "intelligent" feature of the `::` markup for code-blocks

((Anlässlich)) TYPO3-Documentation/TYPO3CMS-Reference-CoreApi#307 (review)

Feedback from Twitter: create one pager quickstart into TYPO3 rst docs for Markdown users and advertise this prominently in different places.

my suggestion would be to create a one pager quickstart into TYPO3 rst docs for Markdown users and advertise this prominently in different places.

https://twitter.com/helhum/status/1246061661699690496

Remove unused parameters from Settings.cfg

As the Settings.cfg in this manual is used as example, it might be good to remove the parameters that are currently unused and add comments to the rest.

These currently do not appear in the generated page:

• description
• t3authors
• version (it does appear in <meta name="book-version", but as release is also used and release is displayed, it seems "version" might be redundant.)

Not sure about these:

[notify]

about_new_builds = no

[html_theme_options]

use_opensearch

Look at "The Good Docs Project" and possibly add to list of resources

https://thegooddocsproject.dev/

This is our list of resources:

• https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingContent/Resources.html

Also, we might want to refer to some Styleguides. Martin recommends Microsoft Style guide, "The Good Docs Project" uses "Google Style guide",

Check link for "good first issue" Issues

https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/HowYouCanHelp.html#fix-issues has link to issues with good first issue.

404 was reported, might be encoding problem with URL?

Currently, this is used:

https://github.com/issues?q=is%3Aopen+is%3Aissue+author%3Asypets+archived%3Afalse+label%3A%22good+first+issue%22+user%3ATYPO3-Documentation

Add information in Help & Support

• how to register for slack (see info in Contribution Guide)
• additionally add possibility to contact team via email

Document how to link to changelog

Slack

From Martin:

① In the CoreApi manual define a mapping in Settings.cfg:

[intersphinx_mapping]
t3core = https://docs.typo3.org/c/typo3/cms-core/master/en-us/

② Use this link:

:doc:`t3core:Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions

This target key is made up of: ⓐ url-mapping-key ⓑ ':' ⓒ relative path ⓓ slug of the document title

The slug is [A-Za-z0-9-_] only, case insensitive. The first title in a reST file is its document title, which is transformed into the slug (=key).

③ Result:
The proper doctitle is shown like

Related

• core issue: https://forge.typo3.org/issues/89330
• decisions: https://decisions.typo3.org/t/done-handle-changelog-vs-main-documentation-for-features/518

Add guidelines for images

There is an Wiki page for images: https://wiki.typo3.org/Documentation_images

Perhaps this could be used to kickstart a section on best practices for creating and embedding images, e.g.

• recommended format for images (png for screenshots, svg?)
• recommend to embed image with :class: box-shadow, :class: with-shadow if this improves readability, see tip of the day

It might also be helpful to provide some templates or hints about how to point out things in the image, since a variety of methods have been used (including arrows, boxes etc.) and it would improve the general look and feel if this were more consistent.

Make sure we inform about reST and Docutils in general

Situation

The basics of reStructureText are documented in the context of 'docutils' and 'reStructureText'.

Pointers to those topics are given here: https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-000/Knowledgebase/HowToDocument/reStructuredText/Index.html#learn-about-the-basics-of-restructuredtext

Task

We, I, should check that that content is part of this repository as well.

Remark

For whatever reason the fundamental reST documentation, for example about the reStructuredText syntax, never got styled. It's hard to read and you'll end up with something like this: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables Nevertheless, this is still the authoritative single point of truth.

When referring to GUI Elements, how should they be spelled?

• When referring to GUI Elements, how should they be spelled?
  • Example rule "When referring to GUI elements, match the capitalization used in the interface." Capitalization
    rules in the IBM developerWorks editorial style guide)

Rename "How you can help" to "Easy ways to contribute"?

This is for example used in https://wiki.typo3.org/Document_Matrix

I never was really happy with the title but did not come up with a better title at that time.

Chapter "Rendering docs" should go to the "How to render" guide

My idea is to have TWO guides like this:

1. How to write (https://docs.typo3.org/typo3cms/HowToDocument/)
2. How to render (https://docs.typo3.org/typo3cms/RenderTYPO3DocumentationGuide/)

This chapter is currently in the wrong guide:
https://docs.typo3.org/typo3cms/HowToDocument/RenderingDocs/Index.html

Update or delete tip of the day: HELP: My extension documentation was rendered with the OLD layout!

https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocForExtension/ExtensionAuthorTips.html#tip-extension-rendered-old-layout

Address CGL indenting 3 space vs. 4 space issue?

The indent with 3 spaces has been in the documentation when I started.

It has been revisited once, see TYPO3-Documentation/T3DocTeam#57. At that point there was not much participation, though it was voiced that some people were unhappy with current 3-spaces and would have liked to change it to 4.

The current status quo is that we have a mixture of 3 and 4 spaces in the docs, but most .editorconfig (in docs and core) contain the 3-space rule.

How should code within code-blocks be indented? I actually saw it pointed out somewhere for our docs that code within code blocks should be indented with 3 spaces as well.

I will try to summarize the pros and cons, but for this some help by others is requested.

Pro 3 spaces

• This is actually used in the sphinx start project (which is not really an argument but gives a hint to the source)
• ... ?

Pro 4 spaces

• Mostly the code-blocks: 4 spaces is used in core, at least for PHP and some others. Copy-pasting code must be done with a change in indenting level
• Editing files directly on GitHub does not give the option to use 3 spaces, only 2 and 4.
• ....

Should we revisit?

• Currently I think it is not a huge problem, but having inconsistent CGL being followed makes some things more difficult. It also makes the docs look not well maintained. After all the effort we put in - not really very satisfactory.
• Not possible to apply automatic CGL checks in the docs currently, as is done in the core. This is something that might be done in the future.

Related

• TYPO3-Documentation/T3DocTeam#57

How to handle translations - technically possible but are we ready for maintaining translations?

I am just adding this issue for easy reference ... - can be put on hold for now ...

See Slack:

My suggestion (2020-07-28)

There are occasionally requests for translating a manual and people offering to do this. I hate to turn them away, but I think we should discourage this if:

• the manual in general is not in good shape: I think it should get updated and be in a good state first, before we start translating
• there is only 1 person offering to do it - I think we should request a group of minimum 2 people maintaining it for at least a year (with one being official maintainer for the language) and commit to this

I realize these are obstacles but we have been reluctant to create translations so I think this is in sync with previous policy but opens a small window of opportunity for someone who is really determined (currently there is a request for Russian in "Tutorial f. Editors")
See also info in "Writing documentation" https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/HowToAddTranslation/Index.html

Anyhow, focus is getting English manuals updated for now!

List of resources for writing documentation

There is already a resources page: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/Resources.html#resources

I would like to collect some more resources here.

Plan documentation writing

• 5 Steps to Create Technical Documentation That’s (Actually) Helpful
• altexsoft: Technical Documentation in Software Development: Types, Best Practices, and Tools

Documentation structure

• What nobody tells you about documentation

These are some questions / classifications:

• target audience by main task e.g. extension developer, core developer, integrator (theme), integrator (configuration) etc.
• target audience by experience level (e.g. beginner (to TYPO3), experienced)
• type of documentation (e.g. reference manual, tutorial, etc.)
  • Explain from the point of view of what is there (e.g. the API in a reference) or a task to be accomplished (e.g. create a theme in a tutorial)
• how to structure the menu(s)

Tips:

• create a (rough) table of contents for entire docs
• create personas and user stories

Other documentation (with good structure)

• PHP Slim Documentation: get started, concepts, start page with "What's the point?", "How does it work"
• Django documentation: start page with "Getting help", "How the documentation is organized", FAQ
• Scrapy FAQ, "Solving specific problems", "Basic Concepts"

Good ideas:

• Put most important stuff and links to most important stuff on the start page (e.g. as a teaser with links to more information)
• most important (most used) things first (on top)
• "New to TYPO3" (instead of "Getting Started"?)
• "Concepts"
• Have an FAQ?
• What can xyz do for you? What's the point?
• "How does it work?"
• "Getting help"
• "Solving specific problems" (aka short "howto guides")
• describe an action "I want to ..."

Writing good content

• “8 Tips for Better Readability” by Roby Collinge

Style Guides

• Microsoft style guide (tip from Martin)

Maintainance and Reviewing

• how to keep documentation up to date?
• how to improve existing documentation (review it). What might be a good workflow?
• how to keep track of what is already up to date / reviewed?

Aspects of reviewing:

in order of importance (roughly)

• technically correct, up to date, adheres to best practices
• didactic : easy to understand. Does it walk the reader through all steps (e.g. for a howto guide)
• helpful is the documentation generally helpful?
• structure and findability: structure of menu, topics easy to find. Linked from start page? SEO. Is the menu consistent throughout the docs so things are easily recognizable (e.g. placement of sitemap)
• formatting: does the formatting make it well readable and skimmable. Is the formatting consistent throughout the docs so similar things are easily recognizable
• language, style (well readable, grammar / spelling ok)
• enough and not too much (should this be documented? Is this something which can be easily looked up in the core? Would documentation be even necessary if the GUI or the API were improved? Should we rather focus on that?

Add things to "How you can help"

Add tasks

• fix title spelling
• fix broken links
• use convention for header formatting (e.g. first level, second level etc.)
• ...

Also, add information (or link to information) about how the task can be done

• Fix broken links : link to reST format for links
• fix title spelling (link to styleguide, see also #17)
• update images: add links to information about how to format images (already done) and guidelines for creating images (don't have this yet, see #11)
• use convention for header formatting (link to header formatting)
• ...

Update / merge / add links: in other manuals

There are chapters / sections in other manuals, where documentation is documented. Some of it is outdated.

todo

• To help maintainability: documentation about documentation can be maintained in one place (this guide). Information in other manuals should be updated, reduced or deleted and links to this guide added.

github.com/TYPO3-Documentation

• https://docs.typo3.org/Contribute/Index.html
• https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-RenderTypo3Documentation ?
• https://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html
• https://docs.typo3.org/Tips/TipOfTheDay/Index.html#how-to-start-documentation-for-your-typo3-extension
• startpage: https://docs.typo3.org/ : Quickstart extension documentation
• Example extension manual
• https://docs.typo3.org/Tips/DocumentationWriters/Index.html
• https://docs.typo3.org/Tips/DocumentationWriters/Extensions/Index.html

external

• add information about Docker to section on rendering? https://typo3worx.eu/2017/02/guide-to-typo3-documentation-part-3-contribute/ (added link to "Writing Documentation" as comment)

How to write & markup menu items

Sometimes you want to point out the steps of opening a menu and you need the complete menu path. How should this be written?

Add some more information on Includes.txt

See Slack, from Martin:

Hello ... there are only three known substitutions "built in": https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#substitutions You can define your own substitutions however: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions We are following the convention to have a single Includes.rst.txt file for a given manual that gets included at the beginning of each and every page. Its purpose exactly is to allow such a global definition and substitution that you are looking for. If you add your definition line - like .. |copyright| replace:: ⓒ 2020 by The Surf Team - in Includes.rst.txt
Keep the include-file in the root folder of the documenation, that is PROJECT/Documentation. And include the file at the beginning of each page like so: .. include:: /Includes.rst.txt . Note that this is the "absolute" path, meaning "root of documentation". So you don't have to adapt relative paths any more when shoving files around.

https://typo3.slack.com/archives/C028JEPJL/p1592250951060100

Common errors for extension documentation (esp. since new rendering)

Collect here. Then decide if documentation needs to be updated or it can be communicated in some other way: in channel / Twitter / blog etc.

• mixup of tabs and spaces. May cause problems with indenting. May even cause pages to not be included in toctree (because pages listed in toctree not indented correctly)

• .. only: html (can be removed)

• Missing Documentation/Settings.cfg : While this used to work for old rendering, it now causes problems: the title is not set. Example: https://docs.typo3.org/p/spooner-web/be_secure_pw/master/en-us/#

  

• Missing title on start page results in missing title. Example: https://docs.typo3.org/p/apache-solr-for-typo3/solr/master/en-us/

Add information about (preview) rendering

This issue does not address the rendering on the documentation server. Here, we are primarily addressing what is relevant for people documenting to get a rendering preview of their changes.

Problem

Information about documentation rendering is in various places. Also, there are currently different methods to render, but usually only one method is explained without further information what is currently recommended.

Also, there are plans to overhaul the rendering on the server, which will also have an effect on how people will render. Since this is not implement yet, we should take it into account, but document what is currently state-of-the-art.
https://docs.typo3.org/News/2018/Index.html#secret-plans-of-better-documentation-rendering

These are (currently) the methods to render documentation as preview:

1. with docker container: https://github.com/t3docs/docker-render-documentation
2. ext:sphinx : https://docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html
3. preview on Github (currently not documented anywhere)
4. Using Starter project: https://docs.typo3.org/Tips/TipOfTheDay/Index.html#how-to-start-documentation-for-your-typo3-extension
5. (outdated) Local sphinx rendering toolchain (without docker): several places

• https://docs.typo3.org/Tips/DocumentationWriters/Extensions/Index.html

Possible solution

• Add a chapter to "How to document" where docker method is explained as
  recommended method
• Link to Readme for docker image on Github from there
• Reduce other places in docs to a stub, remove outdated information and link to "How to document"
• Check if Rendering guide is still up-to-date, consider if parts can be moved to "How to document" or "T3docsteam" or deleted and this guide taken offline

Changes made here as proposed by @DanielSiepmann

To be clarified

• What are the recommended and supported methods (besides docker method)
• Is ext:sphinx method still recommended / supported?

Add Words to Style Guide / Spelling Reference

Add some terms that are commonly used in the docs to Content Style Guide & Spelling Only add terms where spelling is currently inconsistent or not obvious.

• Since spelling in title (headlines) follows different rules, here we focus on how words are spelled when not in title.
• Because the spelling can differ from context to context: Try to add additional context as example sentences, how the term might be used in a sentence or phrase or link to a good example for usage.

Current best choice in bold.

• "backend" (alternate spellings, discouraged: "back-end", "back end")
  • possible rule: "backend" if used as general backend, "Backend", if used in the sense of the TYPO3 Backend
  • example: "When you log into the backend, make sure to ..."
  • see frontend in this list
• "Code Sprint", "code sprint"
  • lowercase is commonly used, see https://en.wikipedia.org/wiki/Hackathon#Code_sprints
• The product Composer is a proper noun and is capitalized, so use that unless you explicitly mean the command composer (see Tools with Executables)
• extension.
  • Example usage: "... includes all TYPO3 extensions that are uploaded to TER" (see TYPO3 Explained: Extension Architecture: Extension Management
• "Extension Manager" or "extension manager"?
• Fluid
• frontend if used in the context of general backend, "Frontend" if used in context of the TYPO3 Frontend, front-end, Front-End, Front End, front end (as noun)
  • differentiation spelling lowercase or uppercase: see backend in this list
  • reason for spelling as one word: "frontend" is most commonly used in docs. Though front-end / "front end" is more commonly used in dictionaries or wikipedia, it appears that "frontend" is not wrong and usage of various forms is common.
  • source: Wikipedia uses "front end" and "front-end"
  • source: Merriam-Webster uses front end (as noun)
  • TYPO3 docs uses various spellings, most common appears to be frontend: see "frontend" in Getting Started, "Frontend", "frontend" and "front-end" in TypoScriptReference
  • see Discussion on "English Language Usage Stackexchange"
• GitHub
• "Introduction Package" or "introduction package"
  • Example usage: “Look for an introduction package to get started” vs “The official TYPO3 Introduction Package is a great place to start”
  • uppercase or lowercase depends on context
• Quickstart / Quick Start / quick start / quickstart
  • source: Wikipedia Quickstart guide lists "Quickstart" and "Quick Start" as spelling
  • example "We have previously provided a Quickstart guide to"
• reST
• "sitepackage" (not "Site Package", "site package")
  • see The Anatomy of TYPO3 Sitepackages, Benjamin Kott
  • see: Sitepackage Builder
  • see: Sitepackage Tutorial
  • as used in context: "site package extension", "sitepackage builder", etc.
  • there was a discussion on Slack in #typo3-documentation. Before, we had used both spellings (site package and sitepackage), as of now, only sitepackage should be used.
• (the) "TYPO3 Core" or "TYPO3 core"
  • Example usage: "The TYPO3 Core comes with a number of icons that may be used in your extension."
• ViewHelper, (not viewhelper, view helper)
  • Use viewhelper, unless you are referring to something that is explicitly spelled ViewHelper (e.g. the directory.
• see also #37

Additional information

capitalization

The most problematic question here (besides the question of one word, two words or hyphenated words, e.g. front-end) is captitalization, e.g. backend or Backend: In general, the trend is to write lowercase, even for specific technical terms, e.g. the internet, see The Verge: AP Style Guide will no longer capitalize internet. In the case of backend: menu is spelled lowercase, why should backend be capitalized?

References

• https://www.grammarly.com/blog/capitalization-rules/
• Guardian and Observer Styleguide : look under capital:

Add information about tables to "ReST & Sphinx Reference"

https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/Reference.html

Update information about documenting extensions

In various places and partly outdated. Maybe some stuff can be merged, other stuff moved to "Writing Documentation":

• https://docs.typo3.org/Extensions/
• https://extensions.typo3.org/faq/#collapseOne1
• https://docs.typo3.org/Tips/DocumentationWriters/Extensions/Index.html
• https://docs.typo3.org/Tips/DocumentationWriters/DocumentationBuild/Index.html#trigger-documentation-rendering

Section in "Writing Documentation": https://docs.typo3.org/typo3cms/HowToDocument/WritingDocForExtension/Index.html

Correct title (headline) capitalization

Check if headlines in this guide conform to Content Style Guide.

See Content Style Guide & Spelling for more information

See Contribute to docs.typo3.org to get started.

FAQ for new documentation rendering

Here, we collect (and answer) open questions. Anyone can grab one of these open questions and add them to the docs.

Please also see FAQ on extensions.typo3.org. We might want to decide, where the information for extension authors should go ...

• on the Migrate page it says I should publish my extension at extensions.typo3.org. I thought this is not required for doc rendering. Is it required at all? What's the advantage?
• I already have a README.rst (or .md) on GitHub (Gitlab, bitbucket etc.). What's the advantage of rendering the docs on docs.typo3.org?

Done

• Is it possible to highjack extension documentation? How do you make sure only the author of the extension publishes the documentation? (see answer below)
• Is there a way to manually trigger docs rendering aside from a Git repository push? (see answer below)
• "the new workflow also means that the documentation and the extension at TER are two separate, independent entities, correct? In theory you could have the documentation in GitHub (for example) and the extension (code) somewhere else (or not in Git at all). You just need to fire the webhook from GitHub/GitLab/Bitbucket to trigger the documentation, correct?" (see Slack)
  • answer: yes
• GitHub (or Gitlab, bitbucket) etc. already automatically render a README.rst (or .md). For TYPO3 documentation I am required to have extra documentation in Documentation folder. This means I have to maintain 2 documentation. Or not?

Find preferred term for "community extension" / "Third party extension"

What is a good term to describe an extension that is not a system extension with following characteristics:

• not included in TYPO3 core
• publicly available

See project for more issues about selecting preferred terms.

What are the conventions for toctrees and sitemaps?

• Do we want a toctree on the startpage and the sitemap on the second page (e.g. Installation & Upgrade Guide? It seems at least one is superfluous.
• Some pages have a toctree on the start page of a chapter, some do not. What are advantages? Best practices?
• Some manuals have Sitemap, some do not
• Some chapters are entirely missing subheaders in the menu (because toctree on startpage has titlesonly). This is not consistent throughout TYPO3 documentation. Since there is a trend to put more on one page (e.g. in TYPO3 Explained), this with titlesonly, these subsections would not be in the menu
  • e.g. Installation Guide & Getting Started

• There are different kinds of approaches in the docs, one is to use only one file with several subsections which doesn't even need to be in a subdirectory (e.g. Topic.rst). Another is to use subdirectories with several files (Topic/Index.rst, Topic/Subtopic1.rst)

Some things people have pointed out / feedback:

• If there is no information about what manual is about you often have to scroll to page 3 (beyond sitemap) to find out what manual is about
• sitemap could be put at the end of manual (not beginning)

Add information about styleguide and link to styleguide

https://typo3.org/community/teams/content/writing-style-guide/

Optimize issue workflow for new contributors

• Add new label "good first issue", use TYPO3 color: #f49800 (use same in all TYPO3 documentation repos)
• Add some new issues that are actually "good first issues" and mark them
• link to this from "How you can help"

see https://help.github.com/articles/helping-new-contributors-find-your-project-with-labels/

Cheat Sheet: Mention Definition Lists only or also good ol' table for references?

Yesterday I reviewed https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/CheatSheet.html and I was thinking about the "table markup" which is used in many core reference manual sections like https://docs.typo3.org/typo3cms/TyposcriptReference/ContentObjects/CoaAndCoaInt/Index.html

I like the result of this approach. If you have many options like in TypoScript it is easier for me to scan those options until you find the right one. (my personal opinion!)

Using Definition Lists "nicely-styled"
is a bit harder to consume (for me). It offers more possibilities.

---

My question are

• Do we have to go with the newer Definition List only?
• Do we have to improve the definition list or add another especially for such scenarios (option reference)?
• Do we have to add the table based approach .. ### BEGIN~OF~TABLE ### also in this documentation?
• Will the table based approach persist and should it be used by documentation authors?

Idea to expand "How you can help" for people who want to make fast contributions

Problem: As a casual contributor, I want a guide on "how to get started quickly." The TYPO3 community said contribution is easy and fast, so show me the main things I need to know fast.

To solve this, I propose making the "How you can help" page more like a quick start. https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/HowYouCanHelp.html

Here are the other similar top-level pages, but seem to be more comprehensive and details.

• How To Document TYPO3 Projects https://docs.typo3.org/typo3cms/HowToDocument/Index.html
• Contains short summary of what that "How to document" manual is
• Contributing to official documentation is a longer introduction https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/Index.html
• Docs » About TYPO3 Documentation » Contribute. Doesn't have as much detail. https://docs.typo3.org/Contribute/Index.html

What do you think about this outline for “How you can help”? It might repeat somethings elsewhere, but could be a good landing page for “I want to do something quick, how can I start?”

• Before your first contribution
  • What they need. GitHub Account, etc. Link to guidelines.
• Explain “Fast online contributions”
  • Small fixes, typos, corrections, etc.
  • Emphasize the workflow is easy, every gets reviewed.
  • Link to the GitHub Method
• What kinds of quick contributions can you make?
  • Similar to what is on here already https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/HowYouCanHelp.html
  • E.g., Start with a favourite manual you’re familiar with.
  • Update content/images/ etc.
• Explain what wouldn’t be a quick contribution
  • Refactoring, new sections, etc.
  • Link to comprehensive docs on the contribution workflow, emphasize if they have ideas to start with an issue.
  • Should link to more info about the contribution workflow. Maybe link to this? https://docs.typo3.org/typo3cms/HowToDocument/WritingDocsOfficial/Quickstart.html

Sort of based on https://symfony.com/doc/current/contributing/documentation/overview.html

Find preferred term for "core extension", "system extension"

See project for more issues about selecting preferred terms.

Add landing pages (start pages) for typical tasks in "Writing Documentation" and add main page "Orientation"

There are several ways for people to get started, e.g. create documentation for extension, contribute via editing on GitHub, or people are already documenting but want to get started on rendering with docker etc.

The idea here is to create 1 start page "Orientation" that will cover all main areas and link to the start page for that are. Then we can just link to that when people are asking questions about how to get started documenting.

Add information how to localize a manual

How to spell anchor texts?

Should text in (link) anchor text be written with title capitalization or as in normal text?

Example: We link to "Spelling Reference" chapter in a manual. Usually this would be spelled "spelling refernce". Example text: "Please see the <Spelling Reference> for more information".

If title capitalization is allowed in anchor text, cross-referencing can be used without always writing out the anchor text, which makes it easier for editors (:ref:t3tca:some-label``)

Document best practices for using text roles (inline code etc.)

Here is described, how to do it : https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/InlineCode.html

Current common practice is using :php: PHP code if inline, other, e.g. :file: and text in backticks.

Additionally, clarify:

• Classnames, e.g. TYPO3\CMS\Core\Html\RteHtmlParser

Clarify

• in standard reST, you can use double backticks, we use single backticks (default textrole)

Might also check, if this is overused, e.g. see:

• https://docs.typo3.org/typo3cms/CoreApiReference/latest/ApiOverview/Database/RestrictionBuilder/Index.html : Here it is also used for TYPO3, TCA.

Does the page start to look cluttered and unreadable?

Use consistent terms

1. find the best terms (term should be clear and have a positive connotation)
2. Add them to page Content Style Guide & Spelling
3. use terms consistently in documentation, also see homepage https://docs.typo3.org

• "community extension" or "3rdparty extension" or ...?
• "core extension" or "system extension" or ?
• "Edit me on GitHub Workflow" (method of editing docs online on GitHub), no longer use "github method", see #27
• "Local Editing and Rendering with Docker", no longer use "git / docker method", see #27

Find and document workflow for using custom image icons (arrows, numbers etc.) for screenshots

Should work with inkscape and using SVG "symbol": https://softwarerecs.stackexchange.com/a/74602/39758

Related:

• #61

See also "old" information in Wiki: https://wiki.typo3.org/DocTeam/Official_Documentation_Screenshots