Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Apache: Docs

Docs Frontpage

 

 

Apache docs RSS feed   Index | Next | Previous | View Threaded


i.galic at brainsware

Apr 10, 2012, 9:06 AM

Post #1 of 5 (302 views)
Permalink
Docs Frontpage

Hey folks,

I'm pulling this specific subject out, because I think the
way we represent ourselves to newcomers is important.

As I mentioned in my last mail, this:

http://httpd.apache.org/docs/current/

is terribly uninviting for several reasons.

The separation in several sub-sections is a good thing,
but the presentation in alphabetical order is bad.

The middle section especially should be ordered in a
way which follows a a certain progress.

"Other Topics" is almost completely useless, in
particular "Other Notes", which duplicates a couple
of links, we no fresh content other than a warning
that the linked content may be outdated.

I'd maybe go as far as replacing the license link with
http://www.apache.org/foundation/license-faq.html

Anyway, I'd like to discuss (or maybe just decide ;)
how we can represent the existing content better.
I'm not trying to force out any howto, intro or other
stuff which some of our users might want..

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rbowen at rcbowen

Apr 10, 2012, 9:18 AM

Post #2 of 5 (286 views)
Permalink
Re: Docs Frontpage [In reply to]

On Apr 10, 2012, at 12:06 PM, Igor Galić wrote:

> As I mentioned in my last mail, this:
>
> http://httpd.apache.org/docs/current/
>
> is terribly uninviting for several reasons.

Agreed. I'd like to see it arranged more invitingly, but my attempts to do so haven't been very successful, possibly because I've been staring at this arrangement for a decade and know where everything is.

>
> The separation in several sub-sections is a good thing,
> but the presentation in alphabetical order is bad.
>
> The middle section especially should be ordered in a
> way which follows a a certain progress.

I wonder if we might arrange things into audiences. Casual users (eg, folks with a web host), server admins, developers.

>
> "Other Topics" is almost completely useless, in
> particular "Other Notes", which duplicates a couple
> of links, we no fresh content other than a warning
> that the linked content may be outdated.

Yeah, "Other" tends to mean "I don't know where to put this", and we need to come up with an organization that eliminates that ambiguity.

>
> I'd maybe go as far as replacing the license link with
> http://www.apache.org/foundation/license-faq.html

+1.

> Anyway, I'd like to discuss (or maybe just decide ;)
> how we can represent the existing content better.
> I'm not trying to force out any howto, intro or other
> stuff which some of our users might want..

We have several distinct audiences that we cater to, and they tend to want their information in different ways. I hesitate to call them beginner, intermediate, and advanced, but that's kind of the structure that stuff might fit into. You mentioned possibly a "where do I start" document, and that's actually been requested numerous times over the years, and derailed in the discussion of what's in scope.

Let's hear some other suggestions of arrangement of this content.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


rumble at cord

Apr 13, 2012, 8:43 AM

Post #3 of 5 (280 views)
Permalink
Re: Docs Frontpage [In reply to]

On 10-04-2012 18:06, Igor Galić wrote:
> Hey folks,
>
> I'm pulling this specific subject out, because I think the
> way we represent ourselves to newcomers is important.
>
> As I mentioned in my last mail, this:
>
> http://httpd.apache.org/docs/current/
>
> is terribly uninviting for several reasons.
>
> The separation in several sub-sections is a good thing,
> but the presentation in alphabetical order is bad.
>
I concur that the front page can be quite difficult to maneuver at
times, and I too would like to see it shaped differently.
I've quite often found that I simply couldn't find what I was looking
for, because my own mental point of entry was more along the lines of
"I'm a developer, where do I start?", which is hidden away in the
"other" section.

I would like for the front page to be, as suggested, more split into
what the exact purpose of the user's visit is, but I have no idea
what-so-ever as to how exactly we would proceed - I suspect we should
make some examples and see what people think about them?

With regards,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


kess at apache

Apr 13, 2012, 11:35 AM

Post #4 of 5 (279 views)
Permalink
Re: Docs Frontpage [In reply to]

On Friday 13 April 2012 17:43:30 Daniel Gruno wrote:
> would like to see it shaped differently.
> I've quite often found that I simply couldn't find what I was looking
> for, because my own mental point of entry was more along the lines of
> "I'm a developer, where do I start?", which is hidden away in the
> "other" section.

Years ago I had a friend moaning about the httpd docs. He said, he could never
find what he was looking for. And if after a lot of searching he got it, he
could not understand it because of his bad english. This has been the impulse
for my translation effort.

Some time later, I realized, translation is not everthing. The current
documentation is written from a developers view. You have to be familiar to
the "httpd language". You already have to know the concepts, possibilities,
and an overview over the existing (or at least the most common) modules. This
is a hughe burden for really new or occasional users.

But I am already to failiar with the Apache to be able to look at the docs
from a beginners view. So some time ago I thought about collecting, sorting
and grouping user questions from users [at] http to get an idea for their
perception. Due to a lack of time I never got into it.

But this approach might help reordering the frontpage.
Imho mostly unexperienced user start there. Experienced users know where to
look and go straight to the correspnding page using the shortest known way
through the navigation.

So let's look at the user questions and collect the corresponding pages which
might have helped them. By the time we might see some group of topics and
corresponding pages. Those should be the base for our new frontpage.

We might - no, I'm sure, we will - also see a lot of questions, which are not
easily answered with our currend docs. Writing new pages and/or improving
existing ones will then be the next step towards an easier to use
documentation.

Regards,
Kess


i.galic at brainsware

Apr 13, 2012, 5:47 PM

Post #5 of 5 (278 views)
Permalink
Re: Docs Frontpage [In reply to]

----- Original Message -----
>
>
> On Friday 13 April 2012 17:43:30 Daniel Gruno wrote:
>
> > would like to see it shaped differently.
>
> > I've quite often found that I simply couldn't find what I was
> > looking
>
> > for, because my own mental point of entry was more along the lines
> > of
>
> > "I'm a developer, where do I start?", which is hidden away in the
>
> > "other" section.
>
>
>
> Years ago I had a friend moaning about the httpd docs. He said, he
> could never find what he was looking for. And if after a lot of
> searching he got it, he could not understand it because of his bad
> english. This has been the impulse for my translation effort.
>
>
>
> Some time later, I realized, translation is not everthing. The
> current documentation is written from a developers view. You have to
> be familiar to the "httpd language". You already have to know the
> concepts, possibilities, and an overview over the existing (or at
> least the most common) modules. This is a hughe burden for really
> new or occasional users.

I think we've toyed with a similar idea sometime back but using
stackoverflow as source.
The data there might be easier accessible/processable

> But I am already to failiar with the Apache to be able to look at the
> docs from a beginners view. So some time ago I thought about
> collecting, sorting and grouping user questions from users [at] http to
> get an idea for their perception. Due to a lack of time I never got
> into it.
>
>
>
> But this approach might help reordering the frontpage.
>
> Imho mostly unexperienced user start there. Experienced users know
> where to look and go straight to the correspnding page using the
> shortest known way through the navigation.
>
>
>
> So let's look at the user questions and collect the corresponding
> pages which might have helped them. By the time we might see some
> group of topics and corresponding pages. Those should be the base
> for our new frontpage.
>
>
>
> We might - no, I'm sure, we will - also see a lot of questions, which
> are not easily answered with our currend docs. Writing new pages
> and/or improving existing ones will then be the next step towards an
> easier to use documentation.

+1

> Regards,
>
> Kess

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

Apache docs RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.