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

[Alex Heizer]

Good evening,


Robert Lemke wrote:

>Good morning, folks!
>  
>
>
>A few months ago we found out that DocBook would be the perfect format for
>us but unfortunately we couldn't handle that technically. In the new TER we
>now use DocBook internally so I suggest that we discuss changing to DocBook
>completely - after a planning and transition phase of course.
>  
>
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.

>>Is there a way we could make a developer extension that can edit the
>>Open Office (or other standard document type) documents in real-time,
>>like you can with a wiki, then save it again, that might be a way to
>>unify a wiki's functionality for a developer, yet still provide a
>>downloadable document for a customer, and keep the site navigation and
>>management features that are T3's strong points. I am not a programmer,
>>so I am expecting a reply something along the lines of "Are you crazy?
>>That would take a year to program!" :) ..but that's what I think we
>>need, more suggestions on how to get from here to there.
>>    
>>
>
>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.

>We certainly need one or more developers in the DocTeam who maintain the
>documentation framework in the long run. If we find such a person I'm
>willing to provide him with my experience about XSLT, DocBook and
>backgrounds of the TER2.
>
>What I'd like to suggest is that you discuss how the perfect framework would
>look like and maybe you even find good examples on other project websites.
>We could then compile a concept and search for an implementor. This would
>also be a project which should be supported by the TYPO3 Association.
>  
>
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

There are a couple of examples of people doing this sort of thing 
already. I mentioned the Blender people (http://www.blender3d.org/) are 
in T3 and using DocBook to maintain and publish their docs, but the 
Bianchi Italian bicycle manufacturer's USA website uses T3 to have 
content editors log in, and get redirected to their front page where 
they edit the content (http://www.bianchiusa.com/1459.html). Then, the 
data gets exported as documents when they need to. 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/).

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.

Thanks for making it all the way to the bottom of the letter! :)

Alex



>Cheers,
>robert
>
>  
>