T3BOARD Documentation notes 2005
<< Back to T3board
Author: Sylvain - Sylvain was member of the DocTeam at this time
notice - Draft
- 1 Documentation note taken during TYPO3 Snowboard tour 2005
- 2 How could we use DocBook as the main documentation format ?
- 3 Needs for the TYPO3 Documentation
- 4 TYPO3 documentation structure
Documentation note taken during TYPO3 Snowboard tour 2005
This document is about the TYPO3 Documentation project. Here is all the transcription of the note I took during the tour 2005.
This Document is oriented to DocTEAM involved people or TYPO3 programmer which want to offer their time to develop new tools for the documentation purpose.
How could we use DocBook as the main documentation format ?
We started with the new idea of switch the whole TYPO3 documentation the the DocBook format. This idea was based on some other big opensource project using also DocBook as their documentation format (PHP, Apache).
This idea is currently dropped because it would involve too much coding to integrate DocBook as our main document system. The second main reason against DocBook is that currently there exists no user-friendly editor for writing DocBooks. However DocBook would bring much more benefit compared to our current documentation format.
Here follow some notes about how we came to such decision :
Here is the main benefits which have been listed during the DocBook case study.
- Bring a strong structure to the Documentation based on the XML grammar used in DocBook.
- Generate the documentation in many ouput formats.
- HTML: one page, multiple pages
- nice printable version through the LaTeX engine
- Use of the file split mechanism provided by DTD entities.
- By chapter or paragraph.
- Any DocBook compliant application could by used to compose our Document (off line editing).
- Some localisation/translation could be generated via a style sheet (XSLT) processing to extract the languages from the main documentation.
- Inside content word tagging with XML markup (filename, classname, etc.).
- Add new visual style to each type of content.
Problem using DocBook for TYPO3 documentation
- Almost no DocBook knowledge to start.
- Any usable and convenient wysiwyg editor + XML validator seem to exists freely for the DocBook grammar.
- Suggested ones are: emacs, vim
- Coding some new BE editor which support the DocBook format seems a very huge work.
- Strong learning curve to learn the DocBook format of ponctual contributor.
- No new major feature that couldn't be done with OpenOffice and some new TYPO3 extension related to the documentation conversion.
Needs for the TYPO3 Documentation
One of the main problem of the TYPO3 documentation is that the volunteers contribute for a very short period of time and don't want to spend time learning any major information about the documentation.
So we need a way to catch their contributions and transform them to something useful for the community.
Will also need the offline contribution offered by OpenOffice document because it's a nice way of introducing input in the TYPO3 Documentation system. This is especially used by Kasper who is one of the major document writer.
We also need some useful tool to improve and facilitate the DocTEAM review. DocTEAM is a very small team of volunteers, 3 or 4 active persons. If they want to be able to produce the expected quality, they need to be assisted by some good tools to facilitate their job.
Current documentation analyze
The documentation is based on OpenOffice document imported on the TER. Part of extension or stand alone document. The document should be written based on an OpenOffice template.
Using the Wiki on https://wiki.typo3.org/ we have created more confusion, because the Wiki is not a structured and functionnal web site, right now. But we have successfully improved the collaboration between document contributor. Which lack from OpenOffice documentation editing.
The whole TYPO3 documentation is pretty complete for the Developper's need, but lack structure and formal tutorial for the beginner.
To help the user (from any level) to find his way through the documentation we need a web semantic approach. That means that a lof (if not all) content should be indexed by related topic. Next some table of content specific to a topic, or multiple topic, could be generated. We can even imagine that the document produced could be exported as new SXW document (See below).
Meta Data missing in the documentation
- Document history (revision + who)
- Date started
- Version of the document
- TYPO3 related version (3.5.0, 3.7.0, 3.8.0, 4.0, etc.)
- curent document status (draft, in progess, proofreading, etc.) (need to be fixed)
- Document type = Manual, reference, tutorial
- There is only 3 types, any example, story, tips, receipe are tutorial.
- Description/summing up
- Could be the introduction part ?
- this information would be listed in some document Matrix view
- Main topic covered by the document (for web semantic default inheritance)
- user annotation
Those informations go into the Database and can be listed as exclude field (TYPO3 permission right). And all should fall under version control too.
Tools improvement suggestion
It was discussed during the snowboard tour about how we could achieve a better documentation editing with TYPO3 itself.
- TYPO3 online documentation editing, like we can do with the Wiki (timtaw for example) (= collaboration tools)
- Nice BE or FE editing which could almost replace OpenOffice
- Metadata about content for any paragraph
- Topic covered
- User annotation right on the right of the section covered (= floating anotation)
- typo3.org better search engine
- Based on user result
- Use also topic/category
- Multiple source merge (topic, indexed document, mailing list, faq)
SXW Import / Export
In order to maintain the documentation cycle we will need a full import/export of OpenOffice document into TYPO3 content element.
New TYPO3 SXW Import mechanism
Importing OpenOffice document in TYPO3 is currently done via the TER php class using a modified version of the General Office Displayer.
The content of the OpenOffice document is not stored in TYPO3 content element. What we would like to improve is to really bind any OpenOffice content to TYPO3 content element. So we could next use some BE editing, may be improved, to contribute to content. We would provide that way a collaborative tool for the TYPO3 documentation project as provided by the Wiki.
Robert Lemke has proposed to bind the whole document into one virtual page in TYPO3. The virtual page will extend the DokType used in page Type. The idea behind the virtual page import is related to the page break and the virtual subpage structure which could be presented in the TYPO3 BE.
That way the tree structure of the document could be generated form its content paragraph level like what is done in the OpenOffice Table of Content.
- One virtual page which is the parent (pid) of all content element of the page
- Only few content element are displayed at the same time in the BE (other are hidden)
- Many virtual subpages made by section base on heder level
- The first time the document is imported in a whole new page (virtual ex:DokType=23)
- The OpenOffice XML content are mapped into TYPO3 content element (tt_content), done by a mapping ruleset.
- The content element are presented using Flex Form.
- Some strange OpenOffice content are mapped to default formating and need to be manual reordered
- The next time a document is imported a new version of the content are created.
- So we can diff/exclude/merge content
- Could we reuse part of the new Import mecanism used in TYPO3 3.8.0 version ?
- What about the server load during the processing of such document in the BE ?
- What about the import process ? (FIXME: See Diagram somewhere)
The Export mecanism should be improved as well.
- export any subpart (virtual subpages) or a whole document
- and reimport it of course !
- The exported document is TYPO3 wellformed (not XML related) based on a SXW template
- The SXW template may contains a set of OpenOffice macro to help the user to keep its document TYPO3 wellformed.
- added MetaData are stored inside the SXW document in variable XML element not displayed in OpenOffice Writer.
TYPO3 documentation structure
I finally got the structure for the whole documentation. It's a come back to the first suggestion made by Kasper in 2003, also used in Peter's structure. It will serve to class any document in the 4 main sections. A document belongs to only one section.
If a document seems to fall into multiple section, chose the best one and put it in. In the other one, start a new document which say that this topic is covered in the other section by the other document.
We will have 4 main sections:
- Getting Started
- a place to learn for beginner, here we put any information which will put the user on the rail.
- the documentation for user who use TYPO3 only to input and manage the content
- the documentation related to TYPO3 administrative task, should be more clearly defined what an administrator is and what is his role.
- the most advanced TYPO3 level, people which develop program, and write template for TYPO3 site.