[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Basic documentation style for better reading

Oh, well, I was reading documentation on packaging and I saw 2 types of pages. Like this one:

http://www.debian.org/doc/packaging-manuals/python-policy/ch-python.html

That has none styles set, and like this one http://www.debian.org/doc/debian-policy/ch-scope.html that has margin: 5px set on body.

About wideness of your screen -- it doesn't matter how wide your screen is. I don't know what is the golden standard, quick search work showed, for example, this http://webtypography.net/Rhythm_and_Proportion/Horizontal_Motion/2.1.2/ -- I'm OK if you choose something different from 800px, but the main idea is that current width is too much for comfortable reading and it should never exceed 800px (or whatever).

I don't think there's an industry standard for this, or it's being hidden somewhere. When I was choosing a comfortable reading width for my blog that has code-samples, I chose 800px and I love it. I find it as a good balance between comfort reading and providing some code samples. Example -- http://www.redhotchilipython.com/posts/2011-06-17-safe-html-wysiwyg.html

Right now I use firebug to set that style while reading debian docs and I can say that it's really so much better now.
(old - http://dl.dropbox.com/u/865508/deb_1.png ,
 new - http://dl.dropbox.com/u/865508/deb_2.png )

Thanks!

On Sun, Mar 11, 2012 at 3:43 AM, Osamu Aoki <osamu@debian.org> wrote:
Hi,

On Sun, Mar 11, 2012 at 02:12:50AM +0200, Kostya Rybnikov wrote:
> Hi!
>
> I'm trying to get started and read HTML docs and what I can say that it is
> hard to read in it's current view.

Please be specific which one.  As I see:
http://www.debian.org/releases/stable/i386/
http://www.debian.org/doc/manuals/debian-reference/
These use
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">

> So I suggest to improve reading process
> by adding small change on HTML generation: add style="max-width: 800px;
> margin: 0pt auto;" inside body tag. That would make a huge difference.
>

Why 800px?  Cell phone may be narrower and my desktop is wider.

What is the reference style guide which support your preference?

Without proper justification, I do not think we have any reason to change.

Is this some well established industry standard?  I have no idea.

Regards,

Osamu

Reply to: