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

DocTeam/Meetings

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

Contents

More current Documentation Team Meeting Minutes

The minutes of newer meetings are available in the DocTeam wiki on forge.

Documentation Team Meeting Minutes 2012-02-23

Attendees

Martin Bless, Philipp Gampe, Michael Schams, Christopher Stelmaszyk, François Suter, Christian Wöbbeking

Topics

  • status of reST migration
    • what to do with the FAL documentation
    • what about using Twitter Bootstrap as a template for HTML rendering?
  • status of template building tutorial
  • discussion on Product Board/Community Council proposal

Status of current projects

  • Michael Schams:
    • Security Guide: Bug fix release maybe in March, later version 1.1.0 with a new chapter on extension development
  • François:
    • Administrative work done:
      • left-over budget from 2011 carried over to 2012 (for reST migration)
      • planned the meeting dates for the first semester of 2012
  • Christopher:
    • received comments and some help on template building tutorial, in particular from Martin Holtz
    • could be ready for publication within a few weeks
  • Martin Bless:

Next meeting

  • Thursday, March 22, 21:00 CET

Documentation Team Meeting Minutes 2012-01-19

Attendees

Martin Bless, Martin Holtz, Christopher Stelmaszyk, François Suter

Status of current projects

  • François:
    • Aim for 2012: Complete the reST migration project
    • Will meet online tomorrow with Martin Bless to check status of project and come up with refined roadmap
  • Christopher:
  • Martin Holtz:
    • Help with TSref maintenance and follow the current works
  • Martin Bless:
    • Got delayed working on migrating existing manuals
    • Learned a lot about Intersphinx while working on client projects
    • Newest version of Spinx has very useful new features, especially for cross-linking with other projects
    • Idea: Developer Days (April 2012): Tutorial Workshop on Working with ReST
  • Status of preview.typo3.org:
    • Blocker solved: Documentation is rendered again.
    • Exact date of release is not known yet
  • Frequency of future meetings:
    • keep monthly events
    • prepare calendar for first half of the year

Documentation Team Meeting Minutes 2011-12-15

Attendes

Martin Bless, Martin Holtz, Christopher Stelmaszyk

Status of the ReST migration

Martin Bless has worked much on ReST.

A new server is online and holds his stuff: Source and rendered version.

Creating HTML documents out of ReST is possible with just one command line command.

In ReST you can use so called directives: E.g. you can include an image writing .. image:: images/user_manual/general.png

Tables can be written as lists. Martin has developed a directive called "field-list-table". It transforms a list and automatically creates a table out of it. Martin has an illusttrative example on of his pages.

  • Column names are defined at the beginning. They are freely choosable (e.g. a, b, c, d oder something like "Property", "Data type", "Description" and so on).
  • For a new table row you can put in a new item: Each item is starting with a small star.
  • Then inside each item you can name the column in which you want to put your text and behind that you can write the text.

A linebreak inside a cell can be made by entering two empty lines. There also is an example on the page linked above.

Here is a link on the syntax of ReST (reStructuredText Markup Specification).

Conversion of our OpenOffice documents: Save OpenOffice document as HTML. Contains content, formatting and meta data. Parsing this HTML is then possible to create different formats, e.g. PDF. Martin plans to do/hopes to do the conversion of the official documents in December. Later than the PDFs and then later some user tools.

ReST in the Wiki

ReST now also is usable in this wiki. For an example see here.

The implementation in the Wiki uses docutils. Since the field-list-table directive is not yet part of docutils, so it is not yet working here. But Martin Bless wants to get it integrated there.

=> ReST support deactivated due to security concerns. May 2013.

Single Sign On in the Wiki

The wiki now uses single sign on with typo3.org. That way people do no longer have to register separately here.

Documentation Team Meeting Minutes 2011-11-23

Attendees

Martin Bless, Martin Holtz, Michael Schams, Christopher Stelmaszyk, François Suter

Introduction by Francois

  • problems in previous meeting, BBB issues, avoid Friday evening as a meeting time
  • next meetings: frequency? => one meeting early December, one in January after the holidays
  • focus: wiki (not discussed last time)

Overview of the Team’s current activities

[MICHAEL SCHAMS]

Security Guide status update:

✔ Security Team finished the review of the document

➜ a native English speaker is currently reviewing the document (language)

➜ outcomes of the language review will be implemented over the weekend

➜ screenshots are a work in progress (I already received a few but not all)

➜ aim: publishing version 1.0.0 in early December 2011


[FRANCOIS]

➜ create a Doodle for the next DocTeam meetings. Aim: one early to mid-December, one in January, then decide again on frequency


[REST-MIGRATION]

✔ Meeting with François, Martin and Sebastian last week

➜ Rendering chain for HTML planned first.

➜ Later create PDF files and other formats

✔ Martin Bless made his field-list-tables directive

➜ François to review the reST version of the official documentation template: http://mbless.de/4us/typo3-oo2rest/The-TYPO3-Sphinx-Theme/build/html/doc_official_documentation_template/official_documentation_template.html


[UPDATE OF OFFICIAL DOCUMENTS]

✔ TSconfig and TCA reference up to date for 4.6

➜ Martin Holtz has begun integrating the media-related objects, he will commit in the next days

➜ TSref needs to be updated for 4.6 ✔ Installation Guide is updated for 4.5

➜ François sends reminder to the Documentation ML to see who can finish the work

✔ Getting Started is not yet up to date for 4.5

➜ François sends reminder to the Documentation ML to see who can finish the work

✔ New template building tutorial: text and screenshots done

➜ Needs proofreading; send an email to the Documentation ML


[WIKI]

➜Knowledge needed about the way how typo3.org handles usernames and how the wiki does it

➜Migration for existing users of the MediaWiki

http://www.single-signon.com/ Helmut Hummel, Rene Fritz integrated something with singleSignOn for typo3.org, can maybe help us

http://svn.wikimedia.org/doc/classAuthPlugin.html API authentification class of MediaWiki

Content for the wiki

➜Information should be at one place only. Wiki for writing manuals

➜Published documents should no longer be in the wiki

➜People must know more clearly how they can help us improve the contents (that often is the reason to create a copy of things in the wiki)

➜Should be solvable with the new documentation on typo3.org (commenting function).

➜Reduce messy structure of content. Create an overview of categories and explain how to use them. As an example: http://en.wikipedia.org/wiki/Portal:Contents/Categorical_index

➜Here is an extension, which might be worth a try: http://www.mediawiki.org/wiki/Extension:CategoryTree

Next meeting

To be decided via Doodle: http://www.doodle.com/kumhfzd5q57z4ics

Legend

✔ done

➜ next steps

☠ impediment

ℹ background info

♫ celebrated

Documentation Team Meeting Minutes 2011-11-11

Meeting with Michael Schams and Francois Suter. Topic: Security Guide (not the wiki)

(Are still in etherpad, which is down currently.)

Documentation Team Meeting Minutes 2011-10-26

Attendees

Francois, Christopher, Martin Bless, Martin Holtz

Introduction by Francois

I propose to have a short overview of recent activities and then concentrate on reST.

Overview of the Team’s current activities

  • Organization
    • François did a lot administrative and organizational work
    • Christopher also organized work
  • Documentation
    • Pending Documentation page
      • will no longer be used for new changes
    • TCA:
      • Updates done by Francois
    • TSconfig:
      • Christian did updates, can be released in the next few days
    • Security Guide:
      • Michael continued his work; 2/3 of all issues done currently
    • TYPO3 Tutorial for Editors:
      • Frederic Darmstädter has nearly finished all new screenshots
    • Templating Tutorial
      • Sabine working on a template. Expecting to be ready soon.
    • TSref:
      • Martin Holtz: integrate the media element into TSref?
      • Needs a check, if the stuff is in tslib or in CSS styled content
  • Wiki
    • Martin Holtz has access to the dev-wiki
  • ReST
    • Sphinx set up. Basis is docutils

reStructured Text

Milestones as highlighted for the DocBook project: http://wiki.typo3.org/DocTeam/DocBook_migration#Milestones

Step 1: Create a sample manual

references: https://git.typo3.org/Documentation/TYPO3/Example/Manual.git/blob/b916a9435b044cfe24e4b210a3616511ccc1cbdd:/OpenOffice/official_documentation_template.pdf

and https://git.typo3.org/Documentation/TYPO3/Example/Manual.git/blob/b916a9435b044cfe24e4b210a3616511ccc1cbdd:/DocBook/manual.xml

Martin's rendering of this manual in reST: http://mbless.de/4us/typo3-oo2rest/The-TYPO3-Sphinx-Theme/build/html/doc_official_documentation_template/official_documentation_template.html

Finishes step 1.

Step 2: Create the rendering scripts

Most things are easy to do.

Problem: Complex tables

Idea to use a directive "list-tables": Write content as unordered lists => transform them into tables.

Even better: "field-list-tables". Creates a better structure in the reST-document. Fabien Udriot is working in that direction, too (related to the BLE projects).

Step 3: Convert the main v4 manuals to reST

Several ways to convert OOffice documents.

1) use XSLT transformation for converting the underlying XML

2) open a OOffice file, convert to HTML and write reST with docutils by adding a reST writer to docutils

Martin B. favors method 2.


Step 4: Make the needed changes to TER, typo3.org and the EM so that the new manuals can be displayed and downloaded

Have HTML, maybe with comments

Maybe also for extensions (optionally)

Step 5: Provide an environment for producing reST

Do what's possible to improve the user experience of writing reST. Ideas include:

1) have a service where people can upload their reST file and test the rendering (to avoid having to install Sphinx on their computer)

2) contribute improvements to http://rst.ninjs.org/ (open source, see: https://github.com/anru/rsted)

reST for non-reST-guys

Is not as difficult as it may look like.

Needs only a small set of rules, somehow comparable to Wiki syntax.

A normal editor works with it (e.g. Notepad++)

Source code of present pages can be viewed and shows how a nice styling/a nice construct can be done.

Most manual writers are developers (who can easily use reST).

reST: Links between documents

Crosslinking between documents works with "labels". Everything can be labeled. As long as the name of the label does not change, the link works.

http://mbless.de/4us/typo3-oo2rest/The-TYPO3-Sphinx-Theme/build/html/probe-x/01-index.html#unique-labels-for-crossreferencing

Labels must be unique inside the "universe" in which they are used. This universe should include TSref, TSconfig, the Core with its sysexts, FLOW5... At the same time they should also be short so that they can be written easily.

They are independant of the name of the document, of the hierarchical structure of the document...

Future tasks and division to the Team Members

  • Updates to documentation to match release of TYPO3 4.6
    • Template Building Tutorial:
      • Christopher: Writes texts until 4. November, then review by Lwam
    • TSref:
      • Martin Holtz has begun integrating three cObjects: Media (which was new in 4.3), QTOBJECT and ...(SWFOBJECT?).
    • TSconfig:
      • Christopher: Make ready for release
  • reST
    • Martin Bless continues work
    • Git-Repository is still missing. Francois pushes this.
  • Meeting concerning structure of reST documentation
    • Sebastian Kurfürst, Martin Bless, Francois, Christopher

Next meeting

Friday, November 11th, 21 o'clock CET

Focus: Wiki

Big Blue Button Meeting 2011-10-13

Attendees

Martin Bless, Frederic Darmstädter, Martin Holtz, Sabine Hueber, Philipp Gampe, Christian Müller, Xavier Perseguers, Christopher Stelmaszyk, François Suter

Introduction by Francois

Proposal to limit meeting duration to 1h max, so that meetings don't drag on forever. Topics that can't be discussed are pushed back to the next opportunity.

Introduction of Team Members

Done (not repeated in the minutes)

Overview of the Team’s current activities

  • Documentation
    • much work done on updating Getting Started, screenshots, translation to Japanese and Dutch
    • TCA reference: Extracted to an own document by Francois. Wants to release for 4.5 and for 4.6 afterwards.
    • TSConfig, update started with the aim of 4.6
    • TSref, needs update for 4.6, need someone
    • work on Security Guide has started, based on a draft from Jochen Weiland. Work being done by Michael Schams, supervision by Helmut Hummel
    • work should start on new Template Tutorial: http://wiki.typo3.org/Template_Building_Tutorial** Wiki
    • Ron Liskey volunteered to help with the wiki
    • Copy of the current server set up as a sandbox for Ron to test
  • ReST
    • Martin Bless was very active. Has used Python before, is a developer, knows reST from there.
  • Other

How to go on with the Wiki

  • General status?
    • Ron Liskey: Security Updates for the Wiki need to be done.
    • Martin Holtz sees himself as a backup for Ron.
  • Administration: What are the tasks which need to be done? How often, how much time?
    • How do they work? Links?
  • Define which content the Wiki should be there for.
    • Problem: Division of content between different sources. Ron?
    • Problem: Duplication of content; maintainability

Template Building Tutorial

http://wiki.typo3.org/Template_Building_Tutorial Opinions about the bold text:

  • Introduction Package or blank/dummy package as basis?
    • Pro Dummy
      • No content in the dummy.
      • t3x for download with pages maybe; optional.
      • maybe better without additional files.
  • Pro Introduction Package
    • Francois: You already have something to start with, but you can also begin from scratch there: add new root page and start from new there.
      • Problem: We would depend on the Introduction Package, which we do not want.
  • Result:
    • Advice to download the dummy. That is also what people will often have later, in real life.
    • But also say: If you downloaded the Introduction Package, add a new root page and start from there. Then the same as when you started with the blank package.** * Result should be similar to Introduction Package.
  • Why TS45Minutes as a basis?
    • Because it explains what "TypoScript Template" means. Clears the possible misunderstanding with "HTML template", which is meant in many other systems, when "Template" is said.
    • TS45 explains role of TypoScript in TYPO3.
    • Goal not to repeat definitions from there.
    • Maybe good to tell the reader to only read certain sections of TS45.
  • Which templating technique to use?
    • Result: Subparts and Markers. That means without any additional helping tool (templavoila, automaketemplate). People should really understand how you match parts of the HTML templates to TypoScript.
    • In advanced Tutorials: With advanced techniques:
      • Fluid way, TemplaVoila, automaketemplate
  • Rough structure of the Wiki page OK?
    • Yes.
    • Maybe even split the first tutorial. Should be short and not boring.
      • page content in part 1
      • menu in part 2
  • Sabine: Maybe have video tutorials for the manual.
    • Silke Arend also does Video Tutorials. Should she join our team?! Why do we not cooperate with her?
    • Problem Maintenance.

Future tasks and division to the Team Members

  • Updates to documentation to match release of TYPO3 4.6
  • Template Building Tutorial:
    • Sabine produces a nice-looking design, which we can use to put the markers in
  • TSref => Martin Holtz does not have too much time, but thinks that small tasks are ideal for him. He will have a look at one or another issue a week.
  • TYPO3 Tutorial for Editors:
    • Needs new screenshots => Frederic Darmstädter
  • Drop Pending Documentation page => François
  • reST
    • continued work

Miscellaneous

None

Next meeting

Arrangements for the next meeting will be made via the documentation mailing list. The aim is to define several dates ahead of time, so that people can plan on being available.


Skype Meeting 2011-02-25

Attendees

Fabien Udriot (FUD), Daniel Brüßler (DBR), François Suter (FSU)

Note

Due to technical issues, the meeting was just a Skype chat and not a conference call. Every one made a summary of his recent activities

Themes

api.typo3.org

  • was officially launched last week
  • Fabien fixed a bug when dowloading ZIP file
  • Fabien added FLOW3 into the API
  • Fabien changed structure / naming to reflect GIT spirit. (e.g. not called trunk but rather master)

ter_doc and ter_fe refactoring

Fabien is in talk with Michael to have a clone on which development/experimenting could be done. It was supposed to be done this week, but could not happen. Maybe next week.

Wiki skinning

Daniel did a lot of work with Sabine. The redesign is about 80% ready.

Wiki server migration

Daniel: the migration is done, but there are issues with the PHP version, etc. The mediawiki software was updated and some extensions now need fixing. In the meantime, the DNS still points to the old wiki, which is read-only.

Official documentation

François:

  • a lot of activity recently, in particular on TSconfig, Getting Started and Installation Guide. The TSconfig updated for TYPO3 4.5 was released.
  • the call for translators also worked very well. About 12 people joined, for various languages. A Russian version of TS in 45 minutes has already been published.

DocBook migration

François: first samples were completed and sent out to the documentation mailing list for discussion. Very interesting discussions have resulted, with very helpful input from Thomas Schraitle, from OpenSuse project.

Budgets

On February 12, 2011, the General Assembly of the TYPO3 Association approved the 2011 budget. This includes two budgets requests for the maintenance of the official documentation and the migration to DocBook. These budgets will start being allocated. François plans to make quarterly assessments. François will write something official about this, so that it's clear for everyone and people don't complaining and claiming money later on. It's great to have budgets, but more transparency is needed now.

Skype Meeting 2011-02-03

Attendees

Fabien Udriot (FUD), Daniel Brüßler (DBR), François Suter (FSU), Sabine Hueber (SHU)

Themes

Wiki skinning

Sabine showed a mockup for the menu: http://www.darmstadt-typo3.de/typowikimenu/menue.html This looks very nice.

See the project page for more details

ter_doc and ter_fe refactoring

Fabien has done a lot of work for improving the ter_doc extensions, understanding how it works and refactoring (http://forge.typo3.org/issues/10460).

Other people are also working on improving ter_fe.

DocBook

François needs to finish the sample DocBook document and submit it for discussion as soon as possible.

François: thinking of the rendering process. How should it happen? ATM, The rendering is done whenever the documentation is released (-> will start the process). It may change a bit in the future as we have more to render (e.g. PDF, HTML, EBook). Example of things to decide: should the process generate a PDF and put it back into the extension or leave it separately somewhere on a server, available for download.
François will start setting up a subproject team to define the design of the Docbook rendering templates. Try to figure out who will be involved. Possible candidates: Marketing team, Thomas Schraitle, Sabine, Jens?

Official Documentation

Work is ongoing. More people are active than before.

Susanne updated the Installation and Upgrade Guide, Christopher updated the TSconfig, François is working on the TCA reference (which he extracted from Core APIs into its own manual).

Sabine talked about fonts and what fonts fit together. The Share font should be used in special cases, not as main text font and not for more than one line of text.

TODO for next time

  • Sabine + Daniel: integrate the menu proposal from Sabine into the wiki, and also the left column
  • François: finish sample DocBook document
  • François: start the discussion about the DocBook release process
  • Daniel: create a module to get connections from other sources to retrieve information into the wiki (e.g. for FLOW3-errormessages, forge-issues)
  • Fabien: start interacting with Steffen Kamper about TER improvements
  • Fabien: continue improving DocBook v5 transformation from OpenOffice documents

Next meeting

Conference call on Friday, February 25th, at 20:30.

Skype Meeting 2010-12-11

Attendees

Fabien Udriot (FU), Daniel Brüßler (DBR), François Suter (FSU)

Themes

Announcements
  • François: Budget for the Docbook migration is on a good way, so that we can get a budget from the association for the Docbook migration. The final decision will come in February.
  • François: Christopher who is active in the bugtracker has been entrusted as member to TSconfig. He appears to be conscientious and will be a good help.
Docbook migration
  • François produced a Mind Mapping Chart which is available at http://wiki.typo3.org/File:DocBookMigration.pdf. The aim of the chart is to sum up the different tasks needed. We are currently at the two point 1 on the PDF (which can be done in parallel).
  • François got inspired by the v5 team and noticed the good work they have produced. He will try generating the OpenOffice layout we have at the moment in XMLmind. Once the thing is ready he will put it on Forge.
  • François reminded that OpenOffice already transforms documentation to Docbook. Unfortunately, the transformation is far from perfect: it has errors and it is still Docbook version 4. However, he raised the idea of improving the exportation so that we could enhance OpenOffice Docbook transformation.
  • Fabien: it is a good idea and is worth a try. This would allow to keep the support of OpenOffice in a first step. We can also imagine a service for the extension developer that would transform the existing OpenOffice manual into Docbook XML online. This service could also do some Wiki export. Thus, the developer would have the choice to manage the documentation whether with Dobook, Wiki or OpenOffice (for some time)
  • François agreed with that. OpenOffice.org may stay for a while, because OpenOffice is still the recommended tool.
  • François: Thomas Schraitle, who is involved with the OpenSuse documentation, said that WYSIWYG editor may be confusing, because that type of editors avoid people focusing on the content.
  • Daniel agreed with that and gave an example that also XML Mind can have that problem. The date tag what can carry a date looks like normal paragraph-text and the last letter of the date entry may be not within the data-tag. Such problems are just seeable when one sees the XML, so it makes sense to have an editor that shows the HTML-rendering on top and the XML below.
Docbook validation
  • François talked about the Docbook validation and that we need to validate the manuals against a RelaxNG scheme.
  • Daniel said that he will add also RelaxNG to the Validator and want to create a RelaxNG what fits to our manuals. We must care for the structure what the FLOW3 manuals have, so that it is not too strict.
  • François said that RelaxNG schemes for Docbook already exist and we can use that and remove the parts we do not need.
  • Ressource http://docbook.org/tdg51/en/html/ch05.html
Translation
  • François asked about the file organisation of translated documentation in the repository. https://git.typo3.org/Documentation/TYPO3/Tutorial/Typoscript45Minutes.git
  • Fabien said it might be a good idea to take over v5 convention and to have already the language as key (en, fr, de, ...)
  • Daniel said we should also think about the language variation such as de_DE and de_AT, like another CMS, with the name eZ Publish, has for its translation texts.
  • We agreed to have this in mind and at it as feature, when we have time for it.

TODO for next time

  • Daniel: will add RelaxNG support to the Validator (https://github.com/patchworker/docbookv), what is written in Java and ship with it the needed rng-files, so that usage is very easy.
  • François: will continue to work on the Docbook structure
  • Fabien: will work on OpenOffice.org Docbook transformation

Upcoming Events

Next Doc Team Meeting: either on the 28th or the 29th (Daniel will organize a Doodle) 9:00 clock Berlin-time via Skype. Over next meeting should be on Friday the 7th of January.

Skype Meeting 2010-12-03

Attendees

Fabien Udriot (FU), Sabine Hueber (SHU), Daniel Brüßler (DBR)

Themes

  • Sabine has worked on the next layout for the wiki. She is "fighting" with the drop down menu at the moment.
  • Daniel has worked on the Docbook validation script which can be used in the console as well as a webservice. The validation is more verbose / complete when done with Java rather than with PHP. More info about the possible parameters coming next meeting. There is an issue opened on Forge. The validation appears to be important since the docbook generated by OpenOffice.org is not valid "out of the box".
  • Fabien has worked on the TER and has tried to make it work locally. Good progress so far as it is possible to render the whole list of extensions.

Upcoming Events

Next Doc Team Meeting: Friday, 10th december, 9:00 clock Berlin-time via Skype

Skype Meeting 2010-11-19

Attendees

Fabien Udriot (FU), Sabine Hueber (SHU), Daniel Brüßler (DBR)

Themes

  • DocBook migration: Status of ter-installation of Fabien and Daniel for development of the ter_doc for DocBook manuals, Ajax-inplace edit "live edit" of the Boost project
  • Wiki Design Rebrush: With orange bar having the most important links and orange as active-state, How to do the navigation on top or on left, Document state (draft - needs a review - can be published), Several official TYPO3 Designs, Orange extjs menu
  • SSO for the wiki / Math captcha in the wiki: The match captcha just for the user-registration, not for the edit-page

Items to prepare for next meeting

  • Info-exchange how to use docondemand like on Susannes Website (FU, Susanne Moog, DBR)
  • Design proposal using an extjs menubar in orange (SHU)
  • Form as honey pot as HTML (FU)
  • Hook-out from edit-action, hook-in to user-registration-action (DBR)

Resources

Upcoming Events

Next Doc Team Meeting: Friday, 3nd december, 9:00 clock Berlin-time via Skype

Skype Meeting 2010-11-5

Attendees

Daniel Brüßler (DBR), Francois Suter (FSU), Susanne Moog (SMO), Fabien Udriot (FU), Sabine Hueber (SHU)

Themes
  • PHP DocBook online editor project
  • DocBook migration project
  • Wiki design rebrush
  • Upload state of TYPO3 Manual
  • todos for next meeting
Items to prepare for next meeting
  • contact with V5 team for DocBook co-operation (FSU)
  • contact with ... to ckeck out resorces for the wiki (DBR)
  • define transformation tool / chain? (how to connect online or offline editor with subversion repository or git) (FU)
  • design proposal (SHU)
  • check Status of GettingStarted, 45minutes manual TODO next time: discuss about strategy migration docbook / wiki (proposal) (SMO)
Further todos

DocBook migration project

in parallel the online tools

  • define the structure
  • relax ng validation scheme
  • list of offline toolslook what V5 team has done
  • maybe custom tags
Resources

http://forge.typo3.org/projects/extension-terfe/repository/show/branches/doc_family

http://wiki.typo3.org/DocTeam/Wiki_Design_Rebrush

Serna Free cross plattform offline editor http://www.syntext.com/products/serna-free/

DocBook Guide in german http://www.suse.de/~toms/transitionguide/howto_de.html

DocBook Relax ng scheme http://www.suse.de/~toms/transitionguide/howto_de.html#relaxngorg

Git http://gitorious.org/

Git xml example http://gitorious.org/kiwi/kiwi/blobs/master/doc/docbook/kiwi-doc-appliance.xml

Ajax example for an online editor http://en.highscore.de/cpp/boost/introduction.html

Aims for documentation (on bottom of site, headline "Documentation") http://en.highscore.de/cpp/boost/introduction.html

Demo installation of PHP DocBook editor http://udriot.net/

Upcoming Events

Next Doc Team Meeting: Friday, 19th november, 9:00 clock via Skype


Skype Meeting 2010-10-22

Attendees

Daniel Brüßler (DBR), Francois Suter (FSU), Susanne Moog (SMO), Fabien Udriot (FU), Sabine Hueber (SHU)

Themes

Items to prepare for next meeting

Resources

Does someone have the links from our chat?

Upcoming Events

Skype meeting 2010-11-5


Phone meeting on Friday 2010-10-15

  • Attendees: Sabine, Daniel
  • Topics: wiki.typo3.org TYPO3-Colors, Lenya installation status
  • Daniel: Lenya 2.03 is a rewrite of the old version what had no installation-problems. The developers don't have the problem and couldn't find the solution. Workaround now is to install a 1.2.x version. The migration will be easy because the content-format didn't change.
  • Other Topic wiki.typo3.org TYPO3-Colors
    • Sabine: Screenshot proposal for the new design. Simpler navigation needed, because there are to many links and buttons in the moment. Needed: move the searchbox above content and people, because the search box is most important.
    • Daniel: Best is to overwrite the CSS and just change a bit of the template what is very important


SkypeChat meeting on Friday 2010-10-08

  • Attendencies: Sabine Hueber (Aims and Design), Susanne Moog (Technical writer), Daniel Brüßler (Team leader and Lenya developer)
  • Voting for team-aim: Meetings for a short time of 30 minutes, at 21:00 (Berlin-time), every friday if possible. The time is enough if we vote using doodle for the next topics before the meeting
  • Skype-problems: Microphone did not work and two times skype terminated itself (Daniel)
  • Sabine: in the moment there's time for the design of the editor
  • Daniel: the URL for the editor will be http://www.javaserv.com, it's not working yet because Java and ant need an update and so compiling showed an error message. The backend of the Lenya CMS is very spartan in comparison with TYPO3, so there is not fileadmin to edit CSS-files or upload images. Things like these have to be done by ftp or ssh. The two important features for us are 1. The documents are directly stored as docBook inclusive the DOCTYPE, 2. In the frontend we can use the WYSIWYG-editor.
  • Sabine: Will get the CSS-files and image-filename from Daniel to design it in TYPO3-style, also FTP-login for the design-folder.
  • Sabine: For the HTML/CSS rendering of the manuals it's best to use divs and not tables, because tables are meant for data
  • Susanne: For specialized books the use of Latex is common, usually not docbook
  • Aims for next meeting (Friday 2010-10-22): Setting Aims instead of collecting todos (Sabine), First docBook-Design online for the TYPO3-editor (Sabine and Daniel)
  • Other Topic typo3.org
    • Daniel: Our team-page is very good now, made by Francois
  • Other Topic Getting started
    • Susanne: Images and the text are ready! Now it can be styled by the new official template, that will be the proof-of-concept for this new one
    • Sabine: What's about presenting the content in small lectures (e-learning)?


First Team-meeting on 2010-10-02 at T3CON10

  • Attendencies: Susanne, Sabine, Tobias, Daniel
  • Aims for next meeting (Friday 2010-10-22): First HTML/CSS Design with Lenya online
  • Aims-definition for the project: How will it be when it's ready? How will it feel to use it? From this we can find the Feature requests, version this aims&featurelist with help of the wiki. Then we can define the use cases for each of the user-roles.
    • Beeing up-to-date with the official manuals and the extension manuals, Providing the manuals in media-neutral format (PDF, single source), Different versions of the manuals for e.g. TYPO3 4.2 Hans/ age 20/ who wants to certify himself
  • Some team aims: adjusting the common aims of all/ the personal itches, be able to solve the taken aims in a short time period, see how the own contributions fits into the whole, everybody can tell ideas and dissenting opinions, topics 2 days before the next meeting, protocol early after the meeting


We need a project management with long-term goals and milestones. The following milestones we began to develop at T3CON10

  • do a specification analysis for the editor
  • define roles and workflows for the content generation process with the new editor
  • define quality control processes (very important!) for the new editor
  • define the aims for the community (How should the editor get integrated in the whole community workflow of content generation? Does something like that exist?)
  • define use cases
  • test all available editors: which editor can implement the specifications best?
  • list the pros and cons
  • choose the editor, which fits the best
  • install it
  • customize the new editor to the needs (design, usability, available functions)
  • define duties and responsibilities in the content generation process
  • implement user management, workflows
  • begin to work
  • be high-fly successful :-)


A new project page with the milestones (as headlines or chapters) would be useful. So we can take one step after another.
Project page for DocBook Editor

Main page (project goals, aims for the community, project members, content overview of subpages)

  • subpage: meeting-protocols
  • subpage: milestones, timeline
  • subpage: specification
  • subpage: roles and workflows
  • subpage: quality control processes
  • subpage: 3 different use cases
  • subpage: available editors, pros and cons

Would be great to speak about the milestones next meeting at friday 2010-10-22.


Meeting Daniel with Robert Lemke on 2010-10-01 at T3CON10

  • We should move as early as possible to docBook. So we use the same format as the FLOW3 and Phoenix Team and it's versionable by subversion
  • OpenOffice.org as editor for docBook is not good enough, because the tags what are used are not always that we need. So important attributes could get lost what are in the document. The other problem is that the style doesn't look like the print-version.
  • Editors can use XMLMind (Node-Editor) as editor
  • Alternative is Oxygen XML-Editor (WYSIWYG)
  • Serna (Open Sourced recently)


Meeting Francois with Robert

The main idea is that we should make sure that v4 and v5 docs converge. This means - in particular - adopting a common infrastructure. The v5 team is currently working with DocBook. It was also planned to migrate the v4 manuals to DocBook a long time ago, but nothing happened eventually.

There would be many advantages in working with DocBook:

  • a more strict structure, since DocBook describes only the structure
  • easier templating, since it is all done upon rendering
  • easier to produce documentation in more formats, as many transformation scripts already exist (targeted formats: HTML, PDF for personal printing, PDF for print-on-demand, ePUB)
  • text-based format, so versioning is possible

The drawbacks are:

  • more technical solution, which may be more complicated to use for editors
  • no ideal tool for editing the documents
  • more initial work to set up all the transformation processes (but will be more cleaner than today)
  • TER and EM need to be adapted

The drawbacks may seem more numerous and some of the tasks daunting, which is probably what held off the migration until now.

Tagging and Categories

For a long time now (about 1 1/2 years), we now have a structure that is built by tagging. It solved all the problems with structuring content we had before.

Now help is needed to help with tagging and deleting the old pages what just wrote about other pages. Now we just have CONTENT e.g. new extension-manuals, team-pages. --Daniel Brüßler 09:47, 11 February 2008 (CET)

Peters 2004 structure proposal

Once again I suggest a structure like the first one on the wiki.

Main_Page history:

My main suggestion is that we should still use skill level as the main way to structure documentation on the wiki. This should be completed with shortcuts to frequently-used pages and maybe some sort of guide (subpages showing another structure/way to existing documents).

Someone raised the objection that

I think it might be hard sometimes, if an article has to be
split into topics for users, administrators and developers.

True, but, here, I have a problem. This is my ideal Main page:

  • There should be only 4-8 distint sections
  • Every wiki page has to fit in
  • A document should fit into just one section

If you can meet the above, you have a good structure! But I know, it is impossible to have all pages fit perfectly and at the same time have few distinct sections.

But IMHO the all/editor/admin/dev structure idea is the best so far... Completed with "DocTEAM corner", News and shortcuts to Glossary and things like that.

My idea of viewing documents in other ways is to have different subpages/guides listing documents...

  • in a matrix
  • for beginners
  • for extension developers
  • and so on

The difference between guides and the Main page would be that guides don´t have to contain all wiki pages, but the Main page should. (Maybe we could have a guide as the main page, and the complete structure at a subpage... )

One problem with documentation structure is that everyone has his or her own idea of it. And as a consequence every compromise will be rejected because it fits no one perfectly...  ;-)

-- Peter 12:34, 13 Nov 2004 (CET)

Documentation structure strategy by Peter June 2004

My suggestion for TYPO3 documentation is many smaller documents rather than a few very big ones. And that documents are divided into distinct categories.

In every category there should be at least one "Basic" document for the average user/subject and then one or more specialised document for special things.

Maybe it is slightly easier to get someone to maintain a 10 page document than it is to get someone to maintain one 100 page document...? But on the other hand there will be more 10 page documents. :-)

I also believe that if every document just cover one topic (say Installation) it will be easier for users to find just the document he/she needs - if all the documentation are well structured/categorised...

-- Peter 21:59, 13 Jun 2004 (CEST)

Peter the one topic of installation is not specifically a good example. Installation is a very broad description for a lot of potentially very detailed topics. These include but are not limited to: File/server permissions, security, platforms, databases, optimization, shared sources, backup, migration and upgrade/downgrade. Personally I think that installation as a topic falls outside of the general TYPO3 discussion. After all TYPO3 is only a PHP script. Almost everything that relates to TYPO3 installation is about general server/script setup rather than TYPO3 configuration. I agree with your general approach to documentation, one overview, one detailed. Those who are professionally qualified will recognize the need for well-structured reference documentation. I see the opportunity for one very large digest of these topics think of them as chapters and each topic area should have one person responsible to accept and make the final changes. I see the structure of TYPO3 documentation pretty ad hoc at present and some coordination is needed to bring it into a sustainable format. I would add to your structure a 3rd section that is general code snippets section. So this leaves 3 documents for each topic. Overview, Detail/Reference & Examples. matthew 08:58, 18 September 2006 (CEST)

November 2004: Suggestions for the structure of the wiki

Structuring tips

First of all I suggest that everyone (involved in this) should read Kaspers document: "Typo3 Documentation Organization".

It is mainly about Developers documentation, but many of his thoughts could, or should, be used for *all* documentation.

The down side is that this document is not very clear on how to really organise documentation! It makes clear of what different criterias and types of documents there are, but then it fails to tell us which of those we should use for structuring! :-(

Four criterias

But in his document he identifies four different criterias to categorize documentation around:

  • Relation (Core, Extension, Installation, Misc)
  • Target group (Users=Editors, Admins, Developers)
  • Type (Reference, manual, examples, tutorials)
  • Skill level (Beginner, Intermediates, Experts)

(I think that Relation could be changed to Subject and that ther could be more/other subjects...?)

Structure based on one criteria

My experience is that a structure should be based on one distinct critera. And I think it should be one of the above.

A few exceptions (max around 5 is my theory) can be tolerated, but the more consistent (to the criteria) the structure is, the easier it is for people to learn it - even if it isn´t thier preferred way of structuring!

And my theory is also that you can never get a structure that everybody likes. But you can get one that is easy to learn! And I believe that a consistent structure is easy to learn.

Try out the structure

So, as a result of this, I recommend that you try to write down rules for where to put documents in the strucuture. If you get only a few rules (say 3-5 short sentenses) then it could/should be a good structure. But if you start with 2-3 rules, and then have to add many exceptions - then I would say it is a bad structure.

You should then take all the existing Typo3 documentation and try to put it into the structure by following the rules. If you still have 3-5 rules after doing that - and didn´t have to add rules for all documents to fit - then I think it is a good structure. Don´t forget to try to include future documents too.

/Peter Kindström

Rainer Suthoelder 2004

Rainer Suthoelder suggestion for structure (form T3-Doc)

Sylvain 2004

Try to use MediaWiki categories

Reported by Daniel

translated from the DseWiki

category-list

FAQ: Are the cats not superfluous, if there are good index-pages?

Answer: To create an index-page means hours of hard work and it's really hard to keep it up-to-date. But to just add a name of a category to a page is easy - so we get an additional structure in little steps. The structure-page of the categories can be used for searching, for maintenance or for creating of new index-pages. So categories and indexes can co-exist in a good way.

--Sylvain Viart 21:06, 13 Nov 2004 (CET)

FAQ: How to name a new category - "Category:Extensions" or "Category:Extension" ?

Answer: Best is to name it in singular style "Category:Extension" - that's common use in some wikis.


I think, I got it! Now we have 2 cats: one for Experiments like the Sandbox, one for discussions. So it is easy to contribute to current discussions :-)

And best is - we can use subcats, too!

Should we make a big cat-concept now? Hm, I would prefer that we play with that new tech for some days and then make a plan. What do you think?


And: Do you all aggree with the tipps what a typed in at the two cat-pages?

>>> Category:Experiment Category:Discussion


Now I mixed the two concepts:

  • first the cats -> The DocumentTeam - category
  • second the templates -> easy-to-use template for a DocTeam-page

<joking> Should I change my name now to "Wizard"? </joking>

--DanielBrüßler

Matthias 2004

Improve Wiki's section visibility. We could use Icon ?

T3-doc Using the Wiki for project collaboration

« I created the new link just for a simple reason: "I didn't see the other one." But such an important point should be clearly visible, shouldn't it. So even using one and the same link, I would recommend to move "other project" related links to a separate block on main page as I did. But again, different views may differ. »

--Sylvain Viart 21:09, 13 Nov 2004 (CET)

Peter 2004

From T3-Doc mailinglist

Have role attached to Document (or part of the document):

  • users
  • administrators
  • developers.

Main page:

  • There should be only 4-8 distint sections
  • Every wiki page has to fit in
  • A document should fit into just one section

If you can meet the above, you have a good structure!

But I know, it is impossible to have all pages to fit perfectly and at the same time have few disctint sections.

Structure:

  • all
  • editor
  • admin
  • dev

Completed with

  • DocTeam corner
  • News
  • shortcuts to Glossary

My idea of viewing documents in other ways is to have different subpages/guides listing documents...

  • in a matrix
  • for beginners
  • for extension developers
  • and so on

The difference between guides and the Main page would be that guides don't have to contain all wiki pages, but the Main page should. (Maybe we could have a guide as the main page, and the complete structure at a subpage... hmmm is that what you are trying to do, Sylvain?)

Daniel 2004

We could add a link "Categories" in the Navigation-part of the left side of each page. It would give the users one MORE possibility to navigate through our wiki.

Hm. I don't think it is possible to include the list-of-categories into the main-page. Because just templates can be included.

Some help with the main-page should be some sweet little templates for that HTML-stuff. Because that HTML-stuff does not make a good "smell" of that wiki-page ;-) -- Daniel

---

So, I added some user-specific-cats. This is what I missed all the time in the old german typo3-wiki. So we get two layers in the wiki

  • the view of the users
  • the view of technological topics

Today I tested how the subcat-concept works. And it does work very good. Now we can built our structure just by defining categories.

I found out that the Special:Category does list ALL cats and subcats. That's not nice if there are more than eight categories. So I created the top-index cat Category:Index.

The cat-concept is very flexible. When we NOW define a optimal category-tree for the wiki we could change it in a half year, if we like.

Look at The cats where I put TemplaVoila in: The wiki-page is very usefull For a Developer and it belongs to the TER-Extension-Category BackendModule.

You can image how we can use it for the wiki-structure? --Daniel

Matthew - the main-page and the wiki structure 2006

Where can we discuss the wiki structure? Currently the wiki welcome page divides the audiences into Editors, Administrators and Developers I am all these things so I don't know where to start looking.

I suggest for the main topics, ie excluding teams etc.

i) Installation ii) TypoScript iii) Extensions

For example:

i) Installation and upgrades This section explores setting up your web server to run TYPO3 effectively. Advanced topics include security, optimisation and backup/migration

ii) TypoScript and TSconfig This topic explores the bulk of TYPO3 reference and configuration. Documents include introductory materials and advanced materials.

iii) Extensions and Development This topic explores existing extensions and the development of your own extensions.

iv) Full document / video / tutorial list. This section is simply a full list of the available resources. Generally these resources will be linked to from the context of other pages within this wiki.

v) Projects and Teams TYPO3 has a wide range of Projects and Teams. This section contains information if you would like to contribute to a team and information for team members.

A significant drawback to the current wiki start page is where to look. If I need more detailed examples of objects from TSref it is not clear where to start looking. Using my approach idea above it is clearer. A second significant drawback of the current wiki start page is that documents are split into many sections Getting Started, Editors, Help, Developers and Extensions etc... matthew 09:26, 18 September 2006 (CEST)



Please read my answer at the newsgroup :-) --Daniel Brüßler 12:30, 18 September 2006 (CEST)

New DocTEAM leader 2004

A vote for the next TYPO3 DocTEAM leader.
Deadline date: Closed 14th november 2004

Method for wiki decisions

Should we use this method of DocTeam meetings to discuss, vote, implement and follow decisions on major things on this wiki?
Deadline date: Closed Saturday 14h August 2004

2004: Template for preparing a decision

Template for preparing a decision - and how to use it.