Mailing List Archive: exim: users

Improving Exim Documentation: A Simple Suggestion

1 2

View All

Index | Next | Previous | View Threaded

exim at temp1

Nov 7, 2009, 7:31 AM

Post #1 of 31 (2690 views)
Permalink

Improving Exim Documentation: A Simple Suggestion

Hallo Boys & Girls,

Just imagine changing your light bulbs for the lower energy consumption
type.

Yes, we know 21w watt new type is bright but supposing some old granny
wants to replace her 100w old type. What can we tell her to help her get
the right replacement ?

Its the same with the Exim 4.69 manual.

Wanting to customise the EXIM I plonked on my VPS, and easily installed
with Yum on Centos (makes a nice change to Windoze 'cos I never had to
reboot the server once) I Googled for information, help and advice.

Eventually I came across Exim manual chapter 39 and customisable error
messages "errmsg_file". When constant interruptions diminished slightly
and I returned to it a week later I searched the Exim web site for
"errmsg_file" and found nothing. Did another goggle on "errmsg_file" and
got

http://www.exim.org/exim-html-3.20/doc/html/spec_39.html

Searched the new documentation (4.69) and disappointingly found no
"errmsg_file". My suggestion is successive versions of manuals should
contain an appendix giving OLD parameters and their replacements. For
example:

errmsg_file .... replaced by bounce_message_file, see chapter 46.1

The same principal applies to granny's light bulbs:-

100w old type ..... replaced by 21w new type.

Regards,

Paul.
[.Programming when there were no hard disks, screens or Micro$oft, just
an occasional drum, cards and papertape].

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

peter at bowyer

Nov 8, 2009, 8:08 AM

Post #2 of 31 (2620 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

2009/11/7 Paul <exim [at] temp1>

>
> http://www.exim.org/exim-html-3.20/doc/html/spec_39.html

Which is a 9-year old document, describing a pre-historic version of Exim.

The only time there have been breaking changes in the config file was
the move from 3.x to 4.x, which is well documented in a file whose
name I've forgotten, but it's included in the 4.x distribution. The
number of people this is still relevant for must be vanishingly small,
and certainly not worth a re-vamp of the current documentation.

Peter

--
Peter Bowyer
Email: peter [at] bowyer
Follow me on Twitter: twitter.com/peeebeee

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

fh-exim2003 at LF

Nov 8, 2009, 1:33 PM

Post #3 of 31 (2608 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On Sun, Nov 08, 2009 at 04:08:20PM +0000, Peter Bowyer wrote:
> >
> > http://www.exim.org/exim-html-3.20/doc/html/spec_39.html
>
> Which is a 9-year old document, describing a pre-historic version of Exim.
>
> The only time there have been breaking changes in the config file was
> the move from 3.x to 4.x, which is well documented in a file whose
> name I've forgotten, but it's included in the 4.x distribution. The
> number of people this is still relevant for must be vanishingly small,
> and certainly not worth a re-vamp of the current documentation.

Please respect the problems of exim-newbies in finding an appropriate
documentation. With little experience that could be a serious problem.
Using a standard google/whatever query you'll get lots of links to
mailing lists and mirrors of mailing lists and only with luck you'll
get a hit for the current documentation.

Just made a little experiment:
Searched in google for "exim message_size_limit" and got not a single
hit for an old or current version of the official documentation
within the first 20(!) pages (not searched further...).

Searching for "exim message_size_limit site:exim.org inurl:exim-html"
Hits http://www.exim.org/exim-html-4.50/doc/html/spec_14.html
in the first place.

So without a doubt the search-engine ranking could/should be improved.

The way to get hits in the latest documentation BTW ist to
include "site:exim.org inurl:current" into the search-string.

--
Regards
Frank

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

peter at bowyer

Nov 8, 2009, 11:30 PM

Post #4 of 31 (2607 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

2009/11/8 Frank Heydlauf <fh-exim2003 [at] lf>:
> On Sun, Nov 08, 2009 at 04:08:20PM +0000, Peter Bowyer wrote:
>> >
>> > http://www.exim.org/exim-html-3.20/doc/html/spec_39.html
>>
>> Which is a 9-year old document, describing a pre-historic version of Exim.
>>
>> The only time there have been breaking changes in the config file was
>> the move from 3.x to 4.x, which is well documented in a file whose
>> name I've forgotten, but it's included in the 4.x distribution. The
>> number of people this is still relevant for must be vanishingly small,
>> and certainly not worth a re-vamp of the current documentation.
>
> Please respect the problems of exim-newbies in finding an appropriate
> documentation. With little experience that could be a serious problem.

Indeed, I've raised that issue myself a number of times. I don't
believe newbies are helped, though, by making it easier to use
9-year-old documentation. Right problem, wrong solution.

> Using a standard google/whatever query you'll get lots of links to
> mailing lists and mirrors of mailing lists and only with luck you'll
> get a hit for the current documentation.

Yep. We need to do some SEO.

Peter

--
Peter Bowyer
Email: peter [at] bowyer
Follow me on Twitter: twitter.com/peeebeee

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

mihamina at gulfsat

Nov 8, 2009, 11:41 PM

Post #5 of 31 (2615 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

11/09/2009 10:30 AM, Peter Bowyer:
>> Using a standard google/whatever query you'll get lots of links to
>> mailing lists and mirrors of mailing lists and only with luck you'll
>> get a hit for the current documentation.
> Yep. We need to do some SEO.

The moinmoin wiki website seems to have a nice idea:
http://master18.moinmo.in/MoinMoin

There is an explicit link to the "current" version.
That could be a good beginning.

--
Architecte Informatique chez Blueline/Gulfsat:
Administration Systeme, Recherche & Developpement
+261 33 11 207 36

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

pete at yerma

Nov 9, 2009, 2:12 AM

Post #6 of 31 (2610 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

While we're at it, could I suggest doing away with the frame or whatever it
is that means the correct url is never shown in the address bar when
browsing exim.org.

Cheers

On Mon, Nov 9, 2009 at 7:30 AM, Peter Bowyer <peter [at] bowyer> wrote:

> 2009/11/8 Frank Heydlauf <fh-exim2003 [at] lf>:
> > On Sun, Nov 08, 2009 at 04:08:20PM +0000, Peter Bowyer wrote:
> >> >
> >> > http://www.exim.org/exim-html-3.20/doc/html/spec_39.html
> >>
> >> Which is a 9-year old document, describing a pre-historic version of
> Exim.
> >>
> >> The only time there have been breaking changes in the config file was
> >> the move from 3.x to 4.x, which is well documented in a file whose
> >> name I've forgotten, but it's included in the 4.x distribution. The
> >> number of people this is still relevant for must be vanishingly small,
> >> and certainly not worth a re-vamp of the current documentation.
> >
> > Please respect the problems of exim-newbies in finding an appropriate
> > documentation. With little experience that could be a serious problem.
>
> Indeed, I've raised that issue myself a number of times. I don't
> believe newbies are helped, though, by making it easier to use
> 9-year-old documentation. Right problem, wrong solution.
>
> > Using a standard google/whatever query you'll get lots of links to
> > mailing lists and mirrors of mailing lists and only with luck you'll
> > get a hit for the current documentation.
>
> Yep. We need to do some SEO.
>
> Peter
>
>
> --
> Peter Bowyer
> Email: peter [at] bowyer
> Follow me on Twitter: twitter.com/peeebeee
>
> --
> ## List details at http://lists.exim.org/mailman/listinfo/exim-users
> ## Exim details at http://www.exim.org/
> ## Please use the Wiki with this list - http://wiki.exim.org/
>
--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

peter at bowyer

Nov 9, 2009, 2:14 AM

Post #7 of 31 (2607 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On 09/11/2009, pete McEvoy <pete [at] yerma> wrote:
> While we're at it, could I suggest doing away with the frame or whatever it
> is that means the correct url is never shown in the address bar when
> browsing exim.org.

Ack. Sounds like we may have a project in the making....

Peter

--
Peter Bowyer
Email: peter [at] bowyer
Follow me on Twitter: twitter.com/peeebeee

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

peter at bowyer

Nov 9, 2009, 2:25 AM

Post #8 of 31 (2611 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On 09/11/2009, Peter Bowyer <peter [at] bowyer> wrote:
> On 09/11/2009, pete McEvoy <pete [at] yerma> wrote:
> > While we're at it, could I suggest doing away with the frame or whatever it
> > is that means the correct url is never shown in the address bar when
> > browsing exim.org.
>
> Ack. Sounds like we may have a project in the making....
>
> Peter

I just created a wiki page to collect ideas. Input welcome.

http://wiki.exim.org/WebsiteImprovements

--
Peter Bowyer
Email: peter [at] bowyer
Follow me on Twitter: twitter.com/peeebeee

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

addw at phcomp

Nov 9, 2009, 2:32 AM

Post #9 of 31 (2614 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On Mon, Nov 09, 2009 at 10:14:35AM +0000, Peter Bowyer wrote:
> On 09/11/2009, pete McEvoy <pete [at] yerma> wrote:
> > While we're at it, could I suggest doing away with the frame or whatever it
> > is that means the correct url is never shown in the address bar when
> > browsing exim.org.

+1

> Ack. Sounds like we may have a project in the making....

Do we have any web designers on this list who want to do this ?

If not I can ask a bunch of web developer friends.

I don't think that we want to spend a lot of time on this, but a freshen
and loosing frames would be good. Doing it with CSS is the way, but this
is where we need a web developer -- who will know what will work in most
browsers.

--
Alain Williams
Linux/GNU Consultant - Mail systems, Web sites, Networking, Programmer, IT Lecturer.
+44 (0) 787 668 0256 http://www.phcomp.co.uk/
Parliament Hill Computers Ltd. Registration Information: http://www.phcomp.co.uk/contact.php
Past chairman of UKUUG: http://www.ukuug.org/
#include <std_disclaimer.h>

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

simon at minos

Nov 10, 2009, 7:13 AM

Post #10 of 31 (2586 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

>> Using a standard google/whatever query you'll get lots of links to
>> mailing lists and mirrors of mailing lists and only with luck you'll
>> get a hit for the current documentation.

Indeed, just had a colleague ask for help with some rewriting changes he
was making to our exim, where he'd followed the documentation and it
wasn't working...

http://www.exim.org/exim-html-2.00/doc/html/spec_toc.html#TOC667

...which he'd found from googling.

He at least had got the correct site, if not anything written this century.

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

exim-users at spodhuis

Nov 10, 2009, 2:39 PM

Post #11 of 31 (2576 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On 2009-11-10 at 15:13 -0000, Simon Beale wrote:
> >> Using a standard google/whatever query you'll get lots of links to
> >> mailing lists and mirrors of mailing lists and only with luck you'll
> >> get a hit for the current documentation.
>
> Indeed, just had a colleague ask for help with some rewriting changes he
> was making to our exim, where he'd followed the documentation and it
> wasn't working...
>
> http://www.exim.org/exim-html-2.00/doc/html/spec_toc.html#TOC667
>
> ...which he'd found from googling.
>
> He at least had got the correct site, if not anything written this century.

Perhaps it's worth post-editing the old documentation to insert a sticky
panel at the top of the viewport which warns, in big letters, "this is
OLD documentation, for release N.NN from YYYY; please go to /FOO for
current documentation" ?

Regards,
-Phil

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

e.sand+exim-users at elisand

Nov 10, 2009, 9:53 PM

Post #12 of 31 (2567 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

> Do we have any web designers on this list who want to do this ?

Indeed we do (looks at self?). If critical imminent deadlines aren't an
issue and the project doesn't become something too large, I could likely
devote some time to it so long as my plate isn't full at the time.

I lurk in the shadows here, so when the time comes just flash the bat
signal...

Eli.

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

mihamina at gulfsat

Nov 11, 2009, 2:37 AM

Post #13 of 31 (2559 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

11/11/2009 08:53 AM, Eli::
>> Do we have any web designers on this list who want to do this ?
>
> Indeed we do (looks at self?). If critical imminent deadlines aren't an
> issue and the project doesn't become something too large, I could likely
> devote some time to it so long as my plate isn't full at the time.

I am also volunteer, but I would suggest using a CMS.
My favorite is Plone.
Using a CMS is IMHO a good solution for documentation.

Have a look at Plone's documentation itself:
http://plone.org/documentation/manual/archetypes-developer-manual
Pages are build lika a book, with chapters and so on.

On the other hand,
- http://www.martinaspeli.net/articles/google-loves-plone
- We try to make some SEO

=> not a bad idea.

--
Architecte Informatique chez Blueline/Gulfsat:
Administration Systeme, Recherche & Developpement
+261 33 11 207 36

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

fh-exim2003 at LF

Nov 11, 2009, 4:10 AM

Post #14 of 31 (2556 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On Tue, Nov 10, 2009 at 02:39:25PM -0800, Phil Pennock wrote:
...
> > He at least had got the correct site, if not anything written this century.
>
> Perhaps it's worth post-editing the old documentation to insert a sticky
> panel at the top of the viewport which warns, in big letters, "this is
> OLD documentation, for release N.NN from YYYY; please go to /FOO for
> current documentation" ?

The "current" documentation is not in any case the "right"
documentation. In example using Debian Etch, the 4.63 is
still the valid one.

I would suggest a more neutral wording like:

Reference Manual for exim 2.00, released 1998
Select manual for your exim version at http://exim.org/somewhere

--
Regards
Frank

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

e.sand+exim-users at elisand

Nov 11, 2009, 8:07 AM

Post #15 of 31 (2557 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

> I am also volunteer, but I would suggest using a CMS.

Not to start an off-topic debate (and this Plone CMS you linked does look
quite nice), but if www.exim.org has mostly static content (as it does now
except for the docs section) there wouldn't be much of a real "need" for a
CMS.

Implementing a CMS or any other technology on the site brings extra
requirements from the hosting (which may also increase costs) as well as
also means added maintenance in terms of staying on top of security issues
with whatever you're using. Staying with static HTML pages and maybe at
worst using SHTML for some dynamic pages keeps server requirements very low
and also reduces the chances of pages being hacked.

So, unless there are big revamp plans for www.exim.org, I would actually
suggest staying with as much static HTML as possible; we can make the site
XHTML 1.1 compliant and use some fancy DHTML stuff if we want, though I
don't think it would require any kind of CMS at this time (especially since
Nigel has already got the experience in maintaining the site as is - editing
a few HTML pages wouldn't be out of place for him).

However, discussion for a later time once plans have been laid out for what
to do with the site :)

Eli.

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

mihamina at gulfsat

Nov 11, 2009, 9:58 AM

Post #16 of 31 (2547 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

11/11/2009 07:07 PM, Eli::
>> I am also volunteer, but I would suggest using a CMS.
> Not to start an off-topic debate (and this Plone CMS you linked does look
> quite nice), but if www.exim.org has mostly static content (as it does now
> except for the docs section) there wouldn't be much of a real "need" for a
> CMS.

- According to me it's not off-topic, it's about Exim
- Having one website subdirectory per version is enough for me to say
it not static.
- 10 years earlier, I would agree about hosting cost and CPU usage. Nowadays,
we have cheap hosting and CPU time + the ability to virtualize almost
anything.

But we're here to talk :-)

--
Architecte Informatique chez Blueline/Gulfsat:
Administration Systeme, Recherche & Developpement
+261 33 11 207 36

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

fh-exim2003 at LF

Nov 11, 2009, 1:24 PM

Post #17 of 31 (2537 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On Wed, Nov 11, 2009 at 08:58:11PM +0300, Rakotomandimby Mihamina wrote:
> 11/11/2009 07:07 PM, Eli::
...
> - Having one website subdirectory per version is enough for me to say
> it not static.
> - 10 years earlier, I would agree about hosting cost and CPU usage. Nowadays,
> we have cheap hosting and CPU time + the ability to virtualize almost
> anything.

What about collecting *requirements* first and after that
deciding what tool to use?

- do we want to convert the old documentation or rewrite
from scratch?
- how easy (if at all) can the old texts be converted into
the new format/system/tool/whatever?
- which output-formats do we want? Only html or pdf as well?,
any others? different output formats for special devices
like PDAs? ...
- what about graphics to include?
- I assume everybody here would prefer an open tool/format
- ... (do some brainstorming yourself)

--
Regards
Frank
docbook, sgml, TeX, xhtml, troff, dita, ... the world is more than html :)

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

mihamina at gulfsat

Nov 11, 2009, 11:06 PM

Post #18 of 31 (2517 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

11/12/2009 12:24 AM, Frank Heydlauf:
> What about collecting *requirements* first and after that
> deciding what tool to use?

You're right.

> - do we want to convert the old documentation or rewrite
> from scratch?

Leave them where they are.
I suggest applying our discussion for upcoming documentation.

> - which output-formats do we want? Only html or pdf as well?,
> any others? different output formats for special devices
> like PDAs? ...

It woul be good to easily be abble to convert the inline documentation to
a paper book.

> - what about graphics to include?

Documentation graphics are part of documentation.
Website styling graphics are part of the tool we use;

> - I assume everybody here would prefer an open tool/format

At least about me, your assumption is right.

--
Architecte Informatique chez Blueline/Gulfsat:
Administration Systeme, Recherche & Developpement
+261 33 11 207 36

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

nigel.metheringham at dev

Nov 12, 2009, 12:39 AM

Post #19 of 31 (2518 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On 11 Nov 2009, at 17:58, Rakotomandimby Mihamina wrote:
> - Having one website subdirectory per version is enough for me to say
> it not static.

Its static. Pages are served directly off disk without any on the fly massaging.

> - 10 years earlier, I would agree about hosting cost and CPU usage. Nowadays,
> we have cheap hosting and CPU time + the ability to virtualize almost
> anything.

Based on previous experience we need a system which needs a close to zero maintenance as possible, because its going to get at most zero maintenance! For example if we used wordpress, then we would have been owned a few years back because no one is able to commit to handle the infrastructure maintenance load.

In particular, after the 4.70 release I am intending to almost completely withdraw from exim work. And I have been doing most of the work recently.

Nigel.

--
[ Nigel Metheringham Nigel.Metheringham [at] InTechnology ]
[. - Comments in this message are my own and not ITO opinion/policy - ]

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

tony at spamexperts

Nov 12, 2009, 1:28 AM

Post #20 of 31 (2517 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On Thu, Nov 12, 2009 at 9:39 PM, Nigel Metheringham
<nigel.metheringham [at] dev> wrote:
> Based on previous experience we need a system which needs a close to zero maintenance as possible, because its going to get at most zero maintenance!

+1 to this.

I think before getting caught up in producing amazing looking
documentation, it's worth trying to resolve the initial
observation/issue here, which is that Google almost never suggests the
current documentation (and often the version suggested is not just
slightly out of date, but < v4). You're reasonably lucky if you get a
first-page link to the docs at all, rather than various forum
postings.

Surely there must be a way to get Google to prioritise the current
documentation (if anyone is specifically looking for older
documentation, then that should be easy to find once you get the
current docs, or they can include the version number in their query).
I know nearly nothing about SEO, but surely this must be the most
basic level?

Cheers,
Tony

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

eximX0902w at linuxwan

Nov 12, 2009, 4:32 AM

Post #21 of 31 (2512 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

On Thu, 2009-11-12 at 22:28 +1300, Tony Meyer wrote:
> Surely there must be a way to get Google to prioritise the current
> documentation (if anyone is specifically looking for older
> documentation, then that should be easy to find once you get the
> current docs, or they can include the version number in their query).
> I know nearly nothing about SEO, but surely this must be the most
> basic level?

A sitemap.xml with appropriate priorities set would get the correct
ordering - possibly. Google just doesn't seem to be picking up the
correct keywords or which pages are important.

front page - 1.0
current docs - 0.9
old docs 0.5 to 0.0 as versions get older.

Don't even consider thinking about meta tags. (Number one sign a SEO
"expert" is clueless)

The one thing I was looking at the last time I downloaded the source for
the documentation (before running away screaming after an hour or two)
was to change all the randomly named anchor tags to something meaningful
for that tag. That was more for humans than google, but it would mean
that the same link would go to the same location in the documentation
when the "current" was swapped, which theoretically would benefit
google. Or split the manual pages up to make segregation easier for
googlebot.

A glossary or book index of the entire documentation might help ..
listing/linking every mention of a particular term.

Maybe slightly more friendly URLs? The last time I piped up about this
we got docs.exim.org and a slightly shorter url, but it still has a fair
whack of useless parts.
www.exim.org/docs/current/index.html introduction.html etc. instead of
exim-html-current/doc/html/spec_html/index.html
Stick the filter spec into the main documentation to avoid that front
page.

Every time I post to the list I've been adding the docs URL in my
signature and any manual references in an attempt to get the
docs.exim.org greater linking (go go one person google bomb!).

The only way I've ever been able to search the exim docs properly has
been use use grep, or "site:exim.org inurl:html-current"

--
The Exim manual - http://docs.exim.org

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

exim-users at lists

Nov 12, 2009, 5:22 AM

Post #22 of 31 (2514 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

Ted Cooper wrote:

> A sitemap.xml with appropriate priorities set would get the correct
> ordering - possibly. Google just doesn't seem to be picking up the
> correct keywords or which pages are important.

Should also update robots.txt to prevent search engines indexing really
old versions of the docs.

Should definitely include these:

Disallow: /exim-html-1.90/
Disallow: /exim-html-2.00/
Disallow: /exim-html-2.10/

Should include these as well IMO:

Disallow: /exim-html-3.00/
Disallow: /exim-html-3.10/
Disallow: /exim-html-3.20/
Disallow: /exim-html-3.30/

As for the static vs dynamic argument, XSLT is perfect for this sort of
documentation. You shove the document content in some simple static
files, and then write separate stylesheets for the html version of the
doc, and the pdf version, etc.

--
Mike Cardwell - IT Consultant and LAMP developer
Cardwell IT Ltd. (UK Reg'd Company #06920226) http://cardwellit.com/
Technical Blog: https://secure.grepular.com/blog/

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

e.sand+exim-users at elisand

Nov 12, 2009, 8:14 AM

Post #23 of 31 (2509 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

Mike write:
> As for the static vs dynamic argument, XSLT is perfect for this sort of
> documentation. You shove the document content in some simple static
> files, and then write separate stylesheets for the html version of the
> doc, and the pdf version, etc.

In terms of browser support, if you are thinking of client-side XSLT, that
support isn't there yet (http://www.w3schools.com/XSL/xsl_browsers.asp). If
you try for server-side XSLT that instantly means you need some form of
script parsing engine like ASP or PHP which can introduce maintenance issues
if the language ever changes (PHP is quite susceptible to this as extensions
change quite a bit in major releases... and hosting providers usually see no
issue in upgrading to newer versions of PHP).

Unless of course you meant using CLI processing to create static output
files, but then that would be just changing how documentation is produced,
not really dealing with changing the website at all.

Eli.

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

Richard.Rogers at staffs

Nov 12, 2009, 8:44 AM

Post #24 of 31 (2509 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

Eli wrote:
"In terms of browser support, if you are thinking of client-side XSLT,
that
support isn't there yet (http://www.w3schools.com/XSL/xsl_browsers.asp"

Am I missing something? As I read that page, it says that current
versions of all major browsers support XSLT (and XML) - not what I
understand by "not there yet".

Regards

Richard

The information in this email is confidential and is intended solely for the addressee. Access to this email by anyone else is unauthorised.

If you are not the intended recipient, any disclosure, copying, distribution or any action taken or omitted to be taken in reliance on it, except for the purpose of delivery to the addressee, is prohibited and may be unlawful. Kindly notify the sender and delete the message and any attachment from your computer.

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

e.sand+exim-users at elisand

Nov 12, 2009, 10:57 AM

Post #25 of 31 (2510 views)
Permalink

Re: Improving Exim Documentation: A Simple Suggestion [In reply to]

> Am I missing something? As I read that page, it says that current
> versions of all major browsers support XSLT (and XML) - not what I
> understand by "not there yet".

You have to support the older browsers when it comes to website design
(unless targeting a select audience in which you can control the browsers
they use), so even though the current browsers support it, that user who's
trying to look up docs for Exim 3.23 may still be using Firefox 2 (or a
handheld device) that may not support it either.

When I said "not there yet", I meant the browser support in general (meaning
the % of browsers used vs how many support XSLT), not that the support for
XSLT didn't exist in browsers yet - apologies for the confusion.

Eli.

--
## List details at http://lists.exim.org/mailman/listinfo/exim-users
## Exim details at http://www.exim.org/
## Please use the Wiki with this list - http://wiki.exim.org/

1 2

View All

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads