Documentation Team Meeting Minutes 2012-07-19¶
Martin Bless, Jacob Floyd, Christopher Stelmaszyk, François Suter, Fabien Udriot,
ReST migration budget¶
- new milestones defined and submitted to EAB
- information posted to the ML: http://lists.typo3.org/pipermail/typo3-project-documentation/2012-July/003966.html
Status of the manuals¶
- Templating Tutorial
- some rewriting is needed
- should be moved to ReST, as editors need to learn how to use that format anyway
- Administrator's Guide
- Michael Schams has begun collecting potential topics; we want to avoid redundancy with other manuals (e.g. the Installation and Upgrade Guide or the Security Guide).
- Michael will ask existing team members if they are still willing to participate and what they would like to do
- Official template
- restore content from the old OpenOffice template
- Git repository from Documentation/TYPO3/Example/Manual.git to Documentation/TYPO3/Example/OfficialManual.git (more explicit)
- Asking for help:
- renaming images
- needs guidelines for making a clean job
- one single image can be used multiple times; search & replace in all Images.txt files should work to replace all occurences
- refreshing screenshots
- should happen only after renaming (or concurrently)
- renaming images
- proposal by Robert Lemke and Jacob Floyd to create improved writing guidelines, including a list a typical non-native English speakers mistakes
- Robert's proposal covers a lot of topics, which we can handle step by step
- it's mostly important for the FLOW3 and Phoenix manuals, which are new, but TYPO3 manuals could be adapted over time
Meta data in conf.py files¶
- it's not satisfying to have meta data in the conf.py file, but it's needed for rendering
- Martin proposes a solution with a Documentation/Settings.yml, which would override default settings from conf.py.
- Martin will provide a patch through Gerrit.
- some discussion going on in the ML to finalize the keys
- the default Intersphinx mapping for official manuals can be included in the Settings.yml file too
- Besides Intersphinx keys - which allow for linking across manuals - it would be nice to have some kind of construct to link to api.typo3.org.
URLs for the docs¶
- some more discussion about the URLs happened in the ML
- globally everyone is ok. The URLs use mixed case, but thanks to Apache's mod_speling they can be typed all lowercase too.
- note: mod_speling will actually rewrite the URL with the proper casing, which is really clean
- the finalized URLs can now be used in the Intersphinx mapping (although they will have to be updated once we switch from "preview.docs.typo3.org")
Labels in reST files¶
- Labels can be used to link to a specified place in the reST file from reST files in another or the same project.
- Martin: Linking headlines alone would not be possible; you would need a label to link to.
- During the build process, a file called "objects.inv" is created, which contains a list of all labels (but this list is decoded in some way).
- It will be an idea to add a list of all labels to the end of each document, so that you have them all at one place.
- Problem: Forgotten updates of that list; is there no easy way (grep?) to find all labels in all Index.rst files?
- should we have standards?
- This can emerge as we go.
- basically labels for headlines could be the same text as the headlines themselves (more or less, maybe simplified)
- for a manual such as the TSref, labels would be the same as the TS properties (beware of properties with the same name, e.g. TEXT and GIFBUILDER's TEXT)
Build chain for the documents¶
Fabien started experimenting with the build chain.
- Current implementation deployed on: http://preview.docs.typo3.org/render/
- Based on F3
- Beanstalk queue service
- Hook install on Gerrit upon a patch merge that triggers documentation
- Outcome put for now: http://preview.docs.typo3.org/render/outcome/
- FLOW3 Package (contains the "logic"): https://github.com/typo3/TYPO3.Docs
- Main repository http://git.typo3.org/Sites/DocsTypo3Org.git
- Open a Forge project and create issues
- Communicate in the ML about the build chain and encourage more helping hands
- Start thinking of the final server
- Thursday, August 23rd, 21:00 CET