Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

DocTeam/Using the official template

From TYPO3Wiki
Jump to: navigation, search
This page belongs to the Documentation Team (category DocTeam)

Working with the official documentation template

All core manuals must use the official documentation template: https://forge.typo3.org/projects/typo3cms-doc-official_template


notice - This information is outdated

The following information still describes the process from the time when the manuals were distributed in TYPO3 extensions. In the future we will use reST instead, which will make our lives much easier in the long term.


Making ready

Fonts

The official documentation template relies on 3 open source fonts:

Make sure all these fonts are installed on your system before using the official template. (Note that OpenOffice also displays the name of the font in the font drop down selector, when you do _not_ have it installed! So just seeing the right name there does not mean, that you see the text in the right font.)

Quotation marks

Make sure that OpenOffice is set to use straight quotation marks. You can do that in OpenOffice: Go to Format > Autocorrect > Autocorrect Options. On the tab Typographical quotation marks you must uncheck the checkboxes "Replace" for "Single quotation marks" and "Double Quotation marks".

Styles

Headings

The headings have been styled anew, but the levels used and the way they are used have not changed.

Main text

The main text should use "Default" and not "Text body" anymore, although both are similar. To switch from "Text body" to "Default", see Migrating to the new template" below.

Lists

There's a paragraph style called "List" which should be applied to bulleted lists. It uses dashes as bullets.

For numbered list, there's a list style called "Numbered list", which may give good results if in a good mood. There's a paragraph style with the same name, but it's proven useless up to now. If you care for your sanity, it actually seems best not to attempt numbered lists with OpenOffice...

Structure

The official documentation template also defines the general structure of official manuals. This *must* be respected.

Cover page

The cover page contains the following elements:

  1. TYPO3 logo: don't touch it!
  2. Document title: change it via File > Properties... > Description > Title
  3. Other OpenOffice: same as title, change them via File > Properties...
  4. Copyright year: adjust the year if necessary
  5. Official documentation notice: for all documentation leave the "Official documentation" notice and remove the "Official documentation translation" notice (do the contrary for translations; NOTE: "official" translations have not been discussed yet).
  6. Document category: leave either the "Core Manual", "Guide" or "Tutorial" notice depending on the type of manual and delete the others. Leave one empty line between this notice and the "Official documentation" notice above.

Note that there's no author and e-mail field anymore for official documentation, as it's not supposed to be changed. Specific authors should be mentioned in the credits (see "Introduction chapter").

The cover page should fit on a single page. If this is not the case (maybe because the official documentation notice and the document category need more space), just remove some blanks in front of them.

Introduction chapter

Every manual must have an "Introduction" chapter and it must at least contain the same 4 sections as the template:

  1. About this document: a brief description of the topics covered by the document. If this manual replaces another one, mention it here.
  2. What's new: highlight important changes from previous version.
  3. Credits: a place to give credits to the people who worked on the manual, and also to mention previous authors (Kasper, for example)
  4. Feedback: this should be left as is. Just complete the URL of the bug tracker related to the manual.

Each of these sections is mandatory. You can however add further small sections as they make sense in your individual case.

Call-out boxes

The official documentation template defines 5 styles of call-out boxes. Each type is described in the template itself.

To use such a call-out box, the easiest way is to copy and paste the relevant box from the template into your document. You may need to adjust the alignment of the icon, but try to avoid that if you can, as this is rather touchy.

Appendices

Official manuals generally did not make use of appendices until now. This is however a good practice. If you feel like some content goes into a lot detail or somehow breaks the flow of the document, think about making it into an appendix.

Appendices are like chapters, but come at the end of the document. Naming should be "Appendix" then an uppercase letter (A, B, C, ...), an em-dash and finally the title of the appendix. Example:

Appendix A – Old stuff

Screenshots

The following guidelines apply when inserting a screenshot in a manual:

  1. when the picture is narrower than the page width, it should be centered (this is the default behavior of OpenOffice anyway)
  2. never use blank lines above or below screenshots. Instead put some spacing around it:
     - select the picture, right-click and choose "Picture...", go to the "Wrap" tab and set top and bottom spacing to 0.2cm.

For creating screenshots, see DocTeam/Official Documentation Screenshots

Migrating to the new template

These are instructions for moving older manuals to the new official template.

Basically just copy and paste the content from the original manual to the new template, excluding the cover page and the table of contents (you probably want to leave the "Introduction" chapter from the template too, as it contains mandatory sections). Then make the few necessary adjustments described below.

Switching styles

Most styles that were used in the old template are still used in the new one. The changes are:

  • "Text body" not used anymore. It is replaced by "Default".
  • "Table Contents/PRE" is replaced by "Table contents preformatted"

To replace all occurrences of one style by another, use the Find & Replace function. Click on "More options" at the bottom of the dialog window and check "Search for Styles". It's then possible to find and replace styles.

Tables

The tables have changed a bit more than the rest.

There's a new style called "Table main item" which is meant to be used in the first column, if relevant. In the case of TypoScript reference - for example - this is the column where the TypoScript property appears. Make sure that you do _not_ change this for the header in this column. Table headers use the styling "Table Header" (with the font "Gillius", non bold), while "Table main item" uses "Baskervald", bold.

There's also a specific style for the "reference index" just below the reference tables (i.e. the things like "[tsref:(cObject).IMAGE]"). It currently uses the "Table Contents" styles. This should be replaced by "Table caption".

The Table header is now styled with a 1pt thick line above and below. Unfortunately it's not possible to define this with a style, so tables have to be edited manually:

  • select all cells in the table's first row
  • go to Table > Table properties... > Borders and define 1pt thick borders above and below. Make sure not to change the other borders.

Lastly, the width of the tables should be reduced by 1cm on both sides. You can best do that by choosing Alignment "Centered" and then giving the table a margin-left of 1cm. If needed, you can adjust the columns as necessary afterwards. Mostly it should be the widest that gets squeezed (which will often be the "description" column), but this may depend on the table.

Update ext_emconf.php

The author name should be changed to "Official Documentation", the email address to "documentation@typo3.org".

Finishing migration

Make sure the document respects all the points described on this page after migration.