Getting All Documentation Under One Roof

Hi,

Can I get a raise of hands who is interested in a more cohesive
partnership between these two sites:

nginx.org
wiki.nginx.org

and what thoughts you have on the best way to do it?

I’m new to Nginx and this mailing list, but I want to help out with
documentation. I spent most of yesterday editing the english wiki at
wiki.nginx.org. My goal was to make it as coherent as possible, and add
the necessary “Getting Started” links to the various pages since it took
me forever to find what I was looking for originally. I also fixed a
couple places where if you hit the wrong link it takes you to a page in
Russian.

The next wave I’d like to pursue is to blend the English wiki and the
english nginx.org site into a more cohesive whole. For example, there
are only a few official documents in English–and a lot of english info
on the wiki. Why not have them both in the same place? Or at least clear
links from one to the other.

My goal, of course, is for all the newbies out there who come along
behind me to be able to find exactly they’re looking for on the first
try.

Jack D.

Technical Writer / Programmer

On Fri, 2011-05-27 at 15:38 -0400, Jack D. wrote:

Hi,

Can I get a raise of hands who is interested in a more cohesive partnership
between these two sites:

nginx.org
wiki.nginx.org

and what thoughts you have on the best way to do it?

Igor writes the documentation on nginx.org. wiki.nginx.org is just
that: a wiki, managed by the community.

IMO, the best thing if you are seeking some cohesion would be to make
sure that docs at nginx.org are properly linked from the wiki and that
they don’t conflict (some info on wiki is outdated or incomplete).

I’m new to Nginx and this mailing list, but I want to help out with
documentation. I spent most of yesterday editing the english wiki at
wiki.nginx.org. My goal was to make it as coherent as possible, and
add the necessary “Getting Started” links to the various pages since
it took me forever to find what I was looking for originally.

Was this due to not knowing the correct search term or something else?

I also fixed a couple places where if you hit the wrong link it takes
you to a page in Russian.

The next wave I’d like to pursue is to blend the English wiki and the
english nginx.org site into a more cohesive whole. For example, there
are only a few official documents in English–and a lot of english
info on the wiki. Why not have them both in the same place? Or at
least clear links from one to the other.

Because one is the official docs and the other is a community wiki. I
don’t think Igor wants random people editing his documentation, nor do I
expect him to update the wiki (that’s our job, as users). Links from
the wiki to the official docs would be good.

My goal, of course, is for all the newbies out there who come along
behind me to be able to find exactly they’re looking for on the first
try.

Cliff

Hi,

On Fri, 2011-05-27 at 15:38 -0400, Jack D. wrote:

Can I get a raise of hands who is interested in a more cohesive partnership
between these two sites:

nginx.org
wiki.nginx.org

and what thoughts you have on the best way to do it?
I think that it would be good to have a bot automatically check pages on
nginx.org, which would add a notification to the wiki.nginx.org site
when a new page was added or an existing one was edited. This would
probably make it easier for those who wish to keep the wiki up-to-date,
since they wouldn’t need to search for what needed checking. There
could also be a section on the notification page for wiki editors to say
that they have looked over the changes and made edits etc, so less
duplication of checking is done.

If the change notifications could have diff information, or perhaps
otherwise identify which configuration directives etc had been added or
changed, this would make the task even easier.

I agree that linking to the original docs would also be useful.

Cheers,

Marcus.

On 29 May 2011 23:03, Jack D. [email protected] wrote:

I’d be in favour of copying the pages of http://nginx.org/en/docs/ into
http://wiki.nginx.org/ along with links to security advisories, books,
etc.
It would need to be kept up-to-date, but this would be a start, unless
Igor
is keen to keep them separate.

I suspect there may be a better way to organise the top-level wiki
sections
(Install, Modules, Add-ons etc.) e.g. I was surprised to find
http://wiki.nginx.org/HttpCoreModule in Modules when I first visited
(it’s
logical, but wasn’t obvious). I also think “Install” on the top level
can be
reworked to incorporate “Getting started” and “Full example”, modified
to
implement auth_basic as well since this can easily be done dangerously
by
first-timers.

So I would love to see two navigation paths streamlined: the path
first-time
users take in downloading, setting up, configuring, and the path
returning
users take getting reference on core, or on modules. Would be happy to
help
implement, if this makes sense to anyone else.

Thomas

On Mon, 30 May 2011 00:44:40 +0200
Thomas L. [email protected] wrote:

I’d be in favour of copying the pages of http://nginx.org/en/docs/
into http://wiki.nginx.org/ along with links to security advisories,
books, etc. It would need to be kept up-to-date, but this would be a
start, unless Igor is keen to keep them separate.

It seems that for anything that is already well-documented on the
official site, we would be better off just linking to it. That way,
whenever the official docs are updated, the wiki doesn’t have to change
with it.

That said, some of the documentation appears to only be available in
Russian. Who is in charge of the translation efforts? I’m happy to help
translate this documentation, especially if they could be put into the
list of official docs.

I suspect there may be a better way to organise the top-level wiki
sections (Install, Modules, Add-ons etc.) e.g. I was surprised to find
http://wiki.nginx.org/HttpCoreModule in Modules when I first visited
(it’s logical, but wasn’t obvious). I also think “Install” on the top
level can be reworked to incorporate “Getting started” and “Full
example”, modified to implement auth_basic as well since this can
easily be done dangerously by first-timers.

I’m with you on that. An easy, streamlined path to get newbies rolling
would be quite helpful.

Jack D.

On Mon, 30 May 2011 00:44:40 +0200
Thomas L. [email protected] wrote:

I suspect there may be a better way to organise the top-level wiki
sections (Install, Modules, Add-ons etc.)

Is there a good way to put a table on contents into a wiki? Newbies
don’t always know what to search for to find what they need.

Jack D.

On Sat, 28 May 2011 01:19:34 +0300
Eugaia [email protected] wrote:

I agree that linking to the original docs would also be useful.

That’s a good idea. I put a link to
http://nginx.org/en/docs/
on the
http://wiki.nginx.org/Resources
page

I’ve also been looking at the organization of the main docs on
nginx.org. It appears that there are a total of seven documents that
comprise the “Official Documentation”, they being:

-How nginx processes a request
-Server names
-Configuring HTTPS servers
-(How to) debugging log
-(How to) converting rewrite rules
-nginx/windows usage
-(FAQ) sys_errlist message

However, it is difficult to see all these articles from a single web
page. I don’t know who manages the site, and noone has asked my opinion,
but I believe it would be more intuitive to find nginx documentation if
http://nginx.org/en/docs/ were a table of contents, laid out like this:

documentation
introduction to nginx
How nginx processes a request
Server names
How to
Configuring HTTPS servers
(Create a) debugging log
converting rewrite rules
security advisories
nginx/windows usage
FAQ

This way one could see all the options from a single, hierarchal glance.

Since “security advisories”, “howto”, and “introduction” are all
contained within this documentation, their links could be removed from
the main page like this:

{languages}
news
about
download
documentation
faq
wiki
links
books
support

which would make the main page cleaner.

Now that’s a good start to making things easy to find. But I notice that
if you look closely, there are additional documents floating around. For
example, go to http://nginx.org/ru/ (The Russian “about” page), and the
text under “Basic HTTP Features” (Основная функциональность
HTTP-сервера) contains not just plain text, but links to more
documentation located at http://sysoev.ru/nginx/docs/. Upon reading some
of these docs, it looks like they comprised the beginning of the
(possibly original?) wiki. And since they’ve been put into the wiki and
not into the official docs page, I wonder if perhaps the plan has been
for the wiki to replace the master docs? What is the overall plan here
for documentation? Which is meant to be the master docs, the wiki or
ngingx.org/docs?

I want to help the cause by getting all the documentation under one
roof, easily accessible, and well-organized. Help me to understand how I
can do this.

Jack D.

On Mon, 30 May 2011 00:44:40 +0200
Thomas L. [email protected] wrote:

I’d be in favour of copying the pages of http://nginx.org/en/docs/
into http://wiki.nginx.org/ along with links to security advisories,
books, etc. It would need to be kept up-to-date, but this would be a
start, unless Igor is keen to keep them separate.

What if all the “official” documentation were folded into the wiki as
locked pages, which Igor would edit? Then the “documentation” link on
nginx.org could simply point to the wiki. Everything would be under one
roof.

Jack D.

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs