DocTeam
From TYPO3Wiki
| Teams R&D-Committee | This page belongs to DocTeam (Members|Contact). see our current activities |
| Support for good documentation is our mission. | |
Contents |
This page is a presentation of the DocTEAM, who we are, how we work and what our goals are.
Todo
FORGE
http://forge.typo3.org/projects/show/team-docteam
Current manuals:
- TSref by Martin and supporters: Wiki De:TSref - see current todo: FORGE martin_currentStuff
The old todo-list: Documentation_joblist - who cares for what topic in the moment.
DocTEAM and Documentation group
The DocTEAM is the group of people who are involved in keeping the documentation effort in the right direction and give their time to convert posts in newsgroups into readable documentation. They help writing tutorials, documentation and manage the content in this wiki and other documentation places directly related to the main TYPO3 community.
The Documentation group is the DocTEAM plus all other contributors who write articles, tips, correct typos, translate pages etc. Any volunteer is welcome and newbies are particularly listened to because of their fresh view of TYPO3 documentation difficulties.
Contact us
If you want to contact the DocTEAM, you can
Project - Documentation-voting
See Documentation-voting - started 2008-03-18
Project - Documentation-manual-editor
See Documentation-manual-editor - started 2008-03-13
FAQ about wiki-documentation
We put it on one page with sections - so it's easier to find the question and answer. But the page will be big ... --Daniel Brüßler 09:11, 21 March 2007 (CET)
New entry: Question: Can I receive an email when a page is updated?
This would be encouraging for extension authors who are interested in maintaining their extension manuals online and want to know when users are having problems, or clean up user-submitted docs.
Answer: check your http://wiki.typo3.org/index.php/Special:Preferences and see if you have authenticated your address. Then you can put some pages to your watchlist. --Daniel Brüßler 20:25, 30 April 2007 (CEST)
Goals
See our Mission Statement and Responsibility.
Our main objective is to have an enterprise class documentation for TYPO3. Here is the directive of what the DocTEAM should do
on a regular basis:
- Organize and review existing documentation.
- Drive the translation of the documentation.
- Maintain the overall documentation structure. See the proposed structure
- Help people to find/use the documentation.
- Create a user-page for people who like to contribute - so it's clearer for them how to ceate new pages
- Redirect them to the right document/page if an answer exists.
- Write some new pages to collect content about special TYPO3 topic.
- Answer questions on newsgroups and write FAQ item.
- Organize and support the work on new and existing documentation.
- Analyse the need for new documentation. Every time we add information somewhere we should ask ourself:
- Is this the right/natural place for the information ?
- If not, is there a better place or should we make a new place ?
- Analyse the need for new documentation. Every time we add information somewhere we should ask ourself:
- Request and drive development of new documentation tools.
Problems of TYPO3-Beginners in the moment
- Beginners think they don't need a book like "Learning TYPO3" as guide for the first steps and try to use the reference-manuals.
- There should be a guide that explains things in order and gets more complex as it goes, building up on previous material. This will eliminate the problem of doing tutorials without really understanding the logic behind them.
- Starters can simply follow the tutorials mechanically without real understanding. e.g. TS by example, MTB. FTB is much better to understand because TV is much easier. Small, simple tutorials would be better. May be even "How to" or "TYPO3 for dummies".
- Many manuals have broken links!!
Roles of users and editors and other keywords
Steps in Learning TYPO3
| english | german |
| Beginner | Anfänger |
| Advanced | Fortgeschrittener |
| Expert | Experte |
Editors of manuals
| Name | Task |
| Developer | The technical view of the documentation. Does often take many things for granted what beginners doesn't know. |
| Copy editor (german: Redakteur/in) | The one who doesn't have to know much about what they are reviewing. These are the editors we need for ensuring that grammar is good, finding typos, and making sure things make sense. |
| Tester | The editor that checks to make sure everything actually works like the manual says, in effect, one learns the software as one is editing. |
Users of TYPO3
- Each one needs his own introduction into TYPO3
- Idea of Dan: There is still some common knowledge they should also have. And then it can break into section for the groups
- WebEmporedChurch does it: For some tasks Wink flashvideos are better than thousand words
| Name | Task | Candidates for the manual-name |
| Simple editor | just inserts content | editor guide |
| Configurator | needs to know all about TypoScript (and some PHP) | administrator guide |
| Administrator | needs knowledge about installatioin and doing backups | administrator guide |
| Extension developer | needs to know the PHP-API (and some TypoScript) | developer guide |
| (new) Core develeoper | needs to know internals | core developer guide |
Other keywords
| keyword | Description |
| broken links | This could be added by an automatic link-checker |
Tags and ControlledVocabulary
| tag-category | Description |
| technical naming | naming defined by the developers (e.g. core, RealURL) |
| structure of IA | tags that build the structure |
two variants how the tags can be set
| how | Description |
| every tag counts | e.g. a category in Wikipedia - if somebody adds it everybody has it as navigation |
| minimum number of same tags | del.ico.us - if a tag is getting "relevant" because several users tagged the content with a tag, then this tag gets "coupled" with the content |
| detailed naming for all users | wikipedia - it's needed to search which categories exist, what is really relevant, know how to set the category, know that they shall be set on the bottom of the page |
| own naming | del.ico.us - everybody can tag with the name what he/she has in mind in the moment |
Document-Lifecycle while creation by teamwork
in the moment just in the wiki
| state-name | example |
| draft | subversion |
| needs a review | csc_with_multimedia |
| publish | typo3_tut |
| stable | pear |
Document-Lifecycle while published
in TER
- This review-stuff should be done by the whole community, one or more buttons next to the document in TER
| review-question | state-name in bugtracker mantis | example |
| Is the manual needed, should it be incorporated into another manual, or should it be eliminated? | major problem/ merge with other document needed | -- |
| Is it up to date, need minor revision, or need major revision? | minor problem/ major problem/ broken link(s) inside/ screenshots too old/ content got wrong because too old | -- |
| What manuals do not exist but are in need by many? | minor problem/ major problem | -- |
Navigation-Paths for documents
| Method | Example | Description |
| page-number | 37 | a pagenumber is wrong after each update of the document |
| textlink/bookmark | [The configuration-reference] | Susanne: TYPO3 instant-sitemap-section-index (that thing you can find inserting a sitemap and selecting section index) for structuring |
| (for printed documents) chapter/subchapter in the footer | "TSref / IMAGE" | Susanne: For printable documents I suggest combining a well-structured table of contents that refreshs itself with printing chapters and subchapters in the footer of each document. So even if the page numbers break the reader can look at the chapter / subchapter in the footer to quickly find the right page |
| TSref - method | [tsref:(cObject).IMAGE] | does work after all updates |
| chapter-number | /extension-manuals/wec_about/1.17.0/view/1/1/#id3849570 | does work after small updates |
HowTo - use OpenOffice and the Wiki to update a manual
Example: extensionkey "typo3_tut"
| Steps | What |
| Prepare the wiki |
|
| Use OpenOffice |
|
| Now again the wikipage |
|
| Community / Teamwork |
|
| Upload to TER |
|
This works properly! --Daniel Brüßler 15:33, 14 March 2008 (CET)
HowTo - Alternative ways
The big table has moved to the project Documentation-manual-editor.
Members
See
HCI could write about Context Sensitive Help (CSH), ECT writes documents about libraries, guidelines, standards and examples, Michael Perkhofer (perki) about Video production, Sebastian Skurfürst cares for the server (PHP, MySQL), Micha Hirdes (Micha Hirdes support-at-elios.de) is caring for us at our hoster bitfarmers.
