[Typo3-doc] Wiki people: who's on board now?

[Robert Lemke]

Hi Alex!

Alex Heizer wrote:

> I think DocBook would be a much better format. The 3D modeling software,
> Blender, has been using it for their documentation for over a year, and
> it allows them to pull it onto their site in an HTML version, publish it
> as a PDF, and publish it as a printed manual, all from the same file.
> They are, incidentally, also using TYPO3 (for at least part of their
> site -- not sure if it's all been transformed yet). In any case, I think
> it would be a good move, and may be easier to utilize in a unified
> document system.

Yes. By using a standard like DocBook we can also use many existing
resources. The DocBook to XHTML transformation I'm using already existed
and only had to be finetuned for our purposes.

>>I don't think this is a crazy idea, it's even a must. What we need is a
>>powerful framework which allows for writing, managing and translating
>>documentation. I am impressed by the enthusiasm and work you have put into
>>the TYPO3 wiki and it showed me that we can use it for collecting
>>information but not for storing the documentation itself.
>>
> I agree, a lot of people have put an insane amount of work into the info
> on the wiki. But then, I've found that BE editing in T3 is very
> wiki-like, in that editors can easily post text, then a collaborator can
> change and add to it. But the point is, the same editing actions need to
> be in the finished system to make collaboration and updating the easiest.

Imagine you had an extension which allows for frontend editing of DocBook
documents in TYPO3. If that would be the perfect solution for us, we could
plan and create it - I mean, we are developers!

> As a framework, I see in the most general sense, a system that:
> * allows an administrator to log in and maintain all the docs at once
> * allows a maintainer to log in and maintain a specific set of docs,
> possibly in the front-end (wiki-like)
> * allows for an edit/publish system (workspaces)
> * multi-language support for translations from a single doc
> * allows a visitor to submit additions/editions that are attached to a
> specific existing or new document from the front-end
> * allows a visitor to download an entire document as a discreet file in
> one or more formats (i.e., PDF, OpenOffice, DocBook, plain text, Palm,
> WAP, etc.)
> * allows an editor (BE maintainer with permissions to edit a specific
> doc) to upload changes from DocBook format if they choose to edit that way
> * provides an RSS feed for monitoring a document, section or entire
> catalog (multiple options for the end-user, *not* only one option
> provided by admins)
> * provides an easy way to set multiple placements on the T3 site (a
> plugin, with LIST, SINGLE, etc. views?)
> 
> There are multiple target audiences for the system, including:
> * Admins/maintainers
> * DocTeam editors
> * Developers
> * T3 site implementers (consultancies, IT staff, Web developers, etc. --
> not core typo3.com/org maintainers)
> * Salespeople in design and consultancy houses
> * Prospective customers
> * Content editors
> 
> Workflows would be different for each audience, and a document flow for
> each type of end-user. For example:
> * T3 site implementers would need technical docs, possibly in PDF, plain
> text or web-based
> * Salespeople in design and consultancy houses would need feature docs
> in PDF, Palm or WAP formats. They may also want OO or plaintext format
> for creating brochures to target a specific sales prospect
> * Prospective customers will want feature lists, and will get the
> information directly from the website or download a PDF for later
> reference * Content editors will want either a PDF or the website
> 
> Editors and admins would need individual workflows. I could see several
> levels of administration:
> * Supreme admins, who keep the project and catalog maintained as a
> system. This includes maintaining users and groups, and troubleshooting
> any problems on a systemwide level (organizing categories, plugin setup
> and placement, etc.)
> * DocTeam admins, who keep an eye on the documentation and make sure
> everything's updated and translated to the most current information
> * Individual doc editors, who are in charge of individual documents and
> are DocTeam members. They will maintain a doc, approve any changes, or
> make updates themselves, and may have an unlimited number of docs they
> are assigned to
> * Developers who write their own documentation. They will have editor
> access only to their doc
> * Website visitors will have a "submit an addition" form that each
> individual doc editor can merge or decline for that doc

> [...]
> And, I'm not sure of 
> the workflow or capabilities (I can't read the German on their website),
> but I've heard that T3N, the TYPO3 Magazine, was written, edited and
> output from within T3 (http://www.yeebase.com/).

I'm have been in contact with Jan Christe from T3N while I was developing
ther ter_doc extension. They don't have a solution we could use out of the
box but they have a lot of XSLT XSL-FO knowlegde and would support us if
needed.

Maybe, before we get lost in big disucussions, we should agree on one person
who collects ideas during a short brainstorming phase and then creates a
concept for the application framework including mockup screenshots. Then we
can refine the concept and finally decide if, how and when we create that
application. This worked pretty well for the TER at least.

> There is room for improvement and more specifics, but I think this
> outlines the basics that we can establish for a system and also provides
> a list of must-have features for a programmer to design and code. Again, 
> I am not a programmer, so I can't recommend whether to incorporate
> existing extensions or start over fresh, and I certainly can't even
> begin to imagine what kind of scope this extension would require as far
> as time and resources. But in order to do it correctly, the above is
> what I see as a minimum we would need to have in order to effectively
> provide everyone with what they will need to create, deliver and use any
> arbitrary piece of T3 documentation. It would certainly be an investment
> to set up initially.

Yes, while you mention it: We definately need 2-3 developers who become
members of the DocTeam and take care of the technical background. We should
create a job description and post it to the dev lists - more ideas?

Cheers,
robert

-- 
Robert Lemke
TYPO3 Association - Research & Development
Member of the board
http://association.typo3.org