[TYPO3] Documentation nightmare

[Christopher Torgalson]

Hi,

On Wed, Mar 19, 2008 at 12:00 PM, Dmitry Dulepov [typo3]
<dmitry at typo3.org> wrote:
> Daniel Bruessler wrote:
>  > I also think so, that's the reason because we compare EVERY solution in
>  > the moment. Hopefully we can use TYPO3 even for the whole
>  > documentation-lifecycle. Let's see ;-)
>
>  This is different. I am not sure if TYPO3 is truly suitable for creating documentation that can be printed. Word processor is better for this task I think.
>
>  I read discussion about using TYPO3 but I am not convinced :)


I'm not completely convinced either, but I do think it's a good idea
to look into. When I think about it, I start to see
advantages--advantages such as maintainers for individual sections of
longer documents such as the TSref. I couldn't, for example, take on
the maintenance of the entire TSref or TS by Example, but I could
certainly commit to maintaining a cObject or two. Using BE logins and
workspaces, we could also semi-automate the process of upgrading major
docs.

Moreover, some parts of manuals--maybe TS property tables?--could be
generated from the source itself (as, e.g. the documentation in the
Ext Dev extension). This would be easier to implement in a web-based
platform than in something like OpenOffice etc.

In addition, while word-processors are good tools for *creating*
documents, they're terrible for reading them. They don't usually have
particularly good navigation tools, and they're often full of
distracting visual 'noise' such as the underlines created by
spell-checkers etc. Web pages and pdfs are much better in general for
electronic reading.

Finally, I think if the community can figure out a fairly robust
system for document creation and publication (i.e. outputting from db
to HTML, sxw, pdf etc), it would be a *terrific* feature for promoting
TYPO3 in certain communications-heavy sectors (i.e. for clients with
large marketing or PR needs). A few years ago I contracted for a
commercial CMS vendor whose product, though demonstrably inferior to
TYPO3 in almost every major feature, was reasonably successful since
it was able to do one thing that most similar tools couldn't: publish
HTML, .doc, .xls and .pdf. Their clientele consisted mostly of
not-for-profits and organizations with large marketing departments who
needed a way of centrally managing content creation and automatically
publishing it in multiple formats at specific times or intervals.

The biggest problem I can think of with respect to document creation
with TYPO3 is, as I mentioned previously, pagination (i.e. given that
there are two different paper sizes in very wide use). But as I also
mentioned, even if this problem could *not* be solved (which I think
is doubtful), it's common in academic circles to refer to specific
locations in text according to numbering systems that do NOT
correspond to physical pages--and it really creates no significant
difficulties.

Finally, some years ago, I suggested on the list that it would be a
great idea to offer printed versions of the major manuals (TSref etc)
for sale via one of the many online publishing services (proceeds to
the association). If the costs were reasonable, I for one would buy a
TSref for each new TYPO3 version (since as things stand, I have to
print the docs myself and have them commercially bound anyway).

-- 
Christopher Torgalson
http://www.typo3apprentice.com/