trafficserver-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Igor Galić <i.ga...@brainsware.org>
Subject Documentation: TODO
Date Thu, 19 May 2011 23:18:44 GMT

Hey folks,

Following my last email, here's a list of things that need attention,
before we can consider exposing our documentation to a larger
user-base. These are things you can do even if you couldn't put
together a coherent sentence at gunpoint.


If you would like to do any of the following points, please reply
to this mail, so people know you're making an effort.

The documentation can currently be found in
https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/
(in content) It's being auto deployed (svnpubsub) to
http://trafficserver.staging.apache.org/

Navigation (Perl)
=================

Right now we have Top|Next|Back style links which
don't seem to work in nested directories: (try the
"Next" link here, and then on the next document)
http://trafficserver.staging.apache.org/docs/trunk/admin/configuration-files/

I've started fiddling around with this
http://paste.ubuntu.com/610332/ + (slight mod to order.txt) to
generate something like this: http://paste.ubuntu.com/609268/ I'm not
sure this is feasible to put on every page, but it should at the very
least be put on the first page.

Anyway, a full [TOC] should be on every page.

CSS
===

Our customers should be able to clearly distinguish the single parts
of a document. So far this works pretty well with code blocks, and
that's about it :) It's very hard to tell at which depth level
(h1-h4) you are

Instead of tables as in the old docs, I have (ab)used definition
lists. The CSS could need some love...

As mentioned above, I'd like to fit a navigation on every HTML page,
while still being able to read it on my tiny laptop - If you think
that's a bad idea, say something!

Fonts
=====

I'm not very sure if the choice of fonts is the right one. I changed
body { font-family: sans-serif; } and it looks better. If you
disagree, say something

Search (HTML/JavaScript)
========================

Our old documentation has a Google search - our new documentation
should have that too! (Or, if you're bored and want to do
solr/lucene...) Our

Links to Doxygen (Perl)
=======================

Our Doxygen reference is currently created by buildbot and deployed
to http://ci.apache.org/projects/trafficserver/trunk/doxygen/ I would
like to have some custom Markdown "macro" which generates a link from
something like $FooBar::baz$ into a link to the appropriate function,
method, namespace, operator or whatever that's supposed to be amc
already has something like this. Bug him.



(My mails just keep getting longer ;)

i

-- 
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/

Mime
View raw message