HOTO Write bad documentation

classic Classic list List threaded Threaded
45 messages Options
123
Reply | Threaded
Open this post in threaded view
|

HOTO Write bad documentation

Nick Holland
We've been seeing a curious number of people offering various kinds of
documentation on various OpenBSD topics.

Most of them are somewhere between minimally useful and outright
destructive and foolish.  I think I've seen precisely one that is
looking very promising...and that was sent to me privately, you haven't
seen it yet.  Obviously, bad documentation is in style now.  However,
people seem to be thrashing around on how to write bad documentation, so
here are some tips based on experience with a number of recent
submissions to misc@...


1) Distribute your document in PDF file format.
Yes, the Web is based on HTML, but hey, it is your document, make it
PDF!  There are at least a couple people who prefer that format (if all
else fails, register a hotmail or yahoo e-mail address under another
name, and say, "I prefer PDF!").  That way, people MUST add additional
software to their system to read your document.  People won't be able to
send you diffs, so you can say honestly, "I received no useful change
suggestions to this document, it MUST be good!".  It also hides the fact
that while you are claiming to be an OpenBSD expert, the only text
editor/formatter you know how to use is MS Word.  A PDF creation program
will hide that very effectively.

Bonus points for formats that are more obscure, less portable, or
require over 500M RAM to open a two page document.


2) Write it as a HOWTO.
Your reader just wants to know how to do the task they have at hand.
After all, we know they are just wanting to accomplish the task, put it
on their resume, and be elsewhere by the time it blows up.  It won't be
their problem by then, anyway!  There is only one way to do most tasks,
those extra knobs are there and set wrong just to confuse the new user,
no one actually uses them differently, EVERYONE does things just like
you suggest.  Theo delights in adding extra "knobs" to OpenBSD and
making sure they are set incorrectly.  Rumors that he actively removes
nonsense options are completely untrue.

No one cares about life-cycle-related issues like upgrades or recovering
from system failures or disasters.

Besides, it is funny to watch people for whom English is not their first
language think "howto" is a valid English word, and is often used with a
question mark at the end ("Howto get my mouse working?"), as a
replacement for "how do I ...?".


3) Write it for an older release.
3.8 was only just shipped, there are surely more 3.7 or 3.6 users that
could benefit from your writing then there are 3.8 users, right?  The
fact that improvements in the most recent release make much of your work
incorrect or less than ideal isn't your problem...


4) Publish it, let it rot.
Don't waste time bringing/keeping your old documents up to date.  There
are so many other things you could be doing, instead.  People will
figure it out.  After all, books don't automatically update on your
shelf, why should a web page be any different?  Besides, PDF files are a
pain to edit, and this way, you don't have to keep track of where you
left the original source.


5) Write a rough draft, put it on misc@, and let the community decide if
it is useful or accurate.
That's what the Internet is about, right?  Freedom to say any damn thing
you wish, regardless of accuracy.  You are supporting free speech,
that's a good thing, right?  BTW, all the people who say you are going
about things wrong are just plain dumb, don't let their @openbsd.org
e-mail addresses fool you.  E-mail can be easily spoofed.  Or they are
trying to repress you.

BTW: The more people you can get irate about your article and tell you
so publicly on the mail lists (quoting the link to your article), the
higher it will be in Google's rankings, permitting more people to find
your wisdom!


6) Good formatting and pretty graphics mean more than actual content.
Obviously, if your page LOOKS good, it must be good.  Complex things
like CSS and browser-specific tricks are great!  Compared to the lame
OpenBSD website, you will look like an absolute authority!


7) When you don't know what is going on, just tell everyone to do what
got things to (sorta) work for you.  Don't waste time by researching
your topic completely, or privately asking people in-the-know to verify
key facts.
The difficulty is clearly the result of the sloppy work of the OpenBSD
developers.  Acknowledging your ignorance of a topic clears your
conscience.  Just say, "I don't understand this, but it worked for me,
so everyone should do this".


8) If you got the thing to work, you are qualified to write a HOWTO.
The more you investigate something, the more annoying issues and special
cases (like maintainability) come up, so don't waste your time.


9) An hour or two is sufficient to spend writing a HOWTO.
Anything more than that is just wasting your time.  The reader will
figure out the things you glossed over.  They were doing that before you
came along, you are helping them, so this is a net improvement, right?


10) Demand that it be put on the OpenBSD website.
Hey, if they don't like it, that can make the tiny little changes
needed.  After all, didn't Thomas Edison say "Genius is one percent
perspiration and ninety-nine percent inspiration"?  You provided the
inspiration, they can do the one percent perspiration, right?  Since
they are an open source project, and they do work for free, you have
every right to demand they adopt your recommendations, after all, they
have no clear direction without you.


Ah, you will note that I failed my own list here, as I called this a
HOWTO, but provided way too much explanation about why you should follow
these tips.  Hey, writing sucky documentation is a difficult skill!


(hopefully, the tongue-in-cheek (or head-in-toilet) nature of the above
was obvious.)

Nick.

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

J.C. Roberts-2
On Fri, 25 Nov 2005 11:55:51 -0500, Nick Holland
<[hidden email]> wrote:

>people seem to be thrashing around on how to write bad documentation, so
>here are some tips

Thanks Nick!

I was wondering which one of the long time folks around here would be
the first to blow a fuse over all the "OpenBSD HOWTO" crap that's been
showing up.

Kind Regards,
JCR

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Han Boetes
In reply to this post by Nick Holland
11) Make documentation unnecesarily complicated. Obfusticate it.

12) Treat critique with violence and disdain.

13) Kick down on other peoples efforts rather than encourage them
    even though they are merely beginners.



# Han

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Michael Shalayeff-2
On Fri, Nov 25, 2005 at 06:30:41PM +0059, Han Boetes wrote:
> 11) Make documentation unnecesarily complicated. Obfusticate it.
>
> 12) Treat critique with violence and disdain.
>
> 13) Kick down on other peoples efforts rather than encourage them
>     even though they are merely beginners.

my all time favourite:

0) never ever bother figuring who actually wrote the stuff
you are "teaching" people to use. when that person shows up
(but you cannot identify him obviously) argue to death on
your own pointless point of view.

cu

--
    paranoic mickey       (my employers have changed but, the name has remained)

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Chris Silva-2
In reply to this post by J.C. Roberts-2
J.C. Roberts wrote:

> On Fri, 25 Nov 2005 11:55:51 -0500, Nick Holland
> <[hidden email]> wrote:
>
>
>>people seem to be thrashing around on how to write bad documentation, so
>>here are some tips
>
>
> Thanks Nick!
>
> I was wondering which one of the long time folks around here would be
> the first to blow a fuse over all the "OpenBSD HOWTO" crap that's been
> showing up.
>
> Kind Regards,
> JCR
>
>
>

Oh hell - why stop there?! Rewrite how users ought to post to the list
along with hot to top post etc.

--
Best regards,
Chris

When you're not in a hurry, the traffic light will turn
green as soon as your vehicle comes to a complete stop.

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

J.C. Roberts-2
In reply to this post by Michael Shalayeff-2
On Fri, 25 Nov 2005 18:35:17 +0100, mickey <[hidden email]> wrote:

>On Fri, Nov 25, 2005 at 06:30:41PM +0059, Han Boetes wrote:
>> 11) Make documentation unnecesarily complicated. Obfusticate it.
>>
>> 12) Treat critique with violence and disdain.
>>
>> 13) Kick down on other peoples efforts rather than encourage them
>>     even though they are merely beginners.
>
>my all time favourite:
>
>0) never ever bother figuring who actually wrote the stuff
>you are "teaching" people to use. when that person shows up
>(but you cannot identify him obviously) argue to death on
>your own pointless point of view.
>

-1) Make certain you are a _CERTIFIED_ professional and make certain you
are wearing the proper safety gear before publicly stuffing your foot in
your mouth, namely, chocolate shoes and flavored socks. And of course,
warn the children not to try this at home...


JCR

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Morris, Roy
In reply to this post by Nick Holland
> -----Original Message-----
> From: [hidden email]
> [mailto:[hidden email]]On Behalf Of
> Nick Holland
> Sent: Friday, November 25, 2005 11:56 AM
> To: misc
> Subject: HOTO Write bad documentation
>
>
> We've been seeing a curious number of people offering various kinds of
> documentation on various OpenBSD topics.
>
> Most of them are somewhere between minimally useful and outright
> destructive and foolish.  I think I've seen precisely one that is
> looking very promising...and that was sent to me privately,
> you haven't
> seen it yet.  Obviously, bad documentation is in style now.  However,
> people seem to be thrashing around on how to write bad
> documentation, so
> here are some tips based on experience with a number of recent
> submissions to misc@...

Bad hair day Nick?  

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Nick Holland
Roy Morris wrote:
...
> Bad hair day Nick?  

Not at all.

At this point in my life, any hair at all is good.  If it wants to look
like I just lost a battle with a Tesla coil, that's fine by me. :)

Nick.

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Sevan / Venture37
In reply to this post by J.C. Roberts-2
J.C. Roberts wrote:

>-1) Make certain you are a _CERTIFIED_ professional and make certain you
>are wearing the proper safety gear before publicly stuffing your foot in
>your mouth, namely, chocolate shoes and flavored socks. And of course,
>warn the children not to try this at home...
>  
>
LOL
good one!
chocolate shoes & flavored socks ey!


Sevan

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Edd Barrett
In reply to this post by Nick Holland
15) Make sure you keep moving the location of your pdf so that no-one
can find it. The more broken links google returns the better.

;)

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Jonathan Glaschke
In reply to this post by Nick Holland
On Fri, Nov 25, 2005 at 11:55:51AM -0500, Nick Holland wrote:

> We've been seeing a curious number of people offering various kinds of
> documentation on various OpenBSD topics.
>
> Most of them are somewhere between minimally useful and outright
> destructive and foolish.  I think I've seen precisely one that is
> looking very promising...and that was sent to me privately, you haven't
> seen it yet.  Obviously, bad documentation is in style now.  However,
> people seem to be thrashing around on how to write bad documentation, so
> here are some tips based on experience with a number of recent
> submissions to misc@...
>
>
> 1) Distribute your document in PDF file format.
> Yes, the Web is based on HTML, but hey, it is your document, make it
> PDF!  There are at least a couple people who prefer that format (if all
> else fails, register a hotmail or yahoo e-mail address under another
> name, and say, "I prefer PDF!").  That way, people MUST add additional
> software to their system to read your document.  People won't be able to
> send you diffs, so you can say honestly, "I received no useful change
> suggestions to this document, it MUST be good!".  It also hides the fact
> that while you are claiming to be an OpenBSD expert, the only text
> editor/formatter you know how to use is MS Word.  A PDF creation program
> will hide that very effectively.
>
> Bonus points for formats that are more obscure, less portable, or
> require over 500M RAM to open a two page document.
>
>
> 2) Write it as a HOWTO.
> Your reader just wants to know how to do the task they have at hand.
> After all, we know they are just wanting to accomplish the task, put it
> on their resume, and be elsewhere by the time it blows up.  It won't be
> their problem by then, anyway!  There is only one way to do most tasks,
> those extra knobs are there and set wrong just to confuse the new user,
> no one actually uses them differently, EVERYONE does things just like
> you suggest.  Theo delights in adding extra "knobs" to OpenBSD and
> making sure they are set incorrectly.  Rumors that he actively removes
> nonsense options are completely untrue.
>
> No one cares about life-cycle-related issues like upgrades or recovering
> from system failures or disasters.
>
> Besides, it is funny to watch people for whom English is not their first
> language think "howto" is a valid English word, and is often used with a
> question mark at the end ("Howto get my mouse working?"), as a
> replacement for "how do I ...?".
>
>
> 3) Write it for an older release.
> 3.8 was only just shipped, there are surely more 3.7 or 3.6 users that
> could benefit from your writing then there are 3.8 users, right?  The
> fact that improvements in the most recent release make much of your work
> incorrect or less than ideal isn't your problem...
>
>
> 4) Publish it, let it rot.
> Don't waste time bringing/keeping your old documents up to date.  There
> are so many other things you could be doing, instead.  People will
> figure it out.  After all, books don't automatically update on your
> shelf, why should a web page be any different?  Besides, PDF files are a
> pain to edit, and this way, you don't have to keep track of where you
> left the original source.
>
>
> 5) Write a rough draft, put it on misc@, and let the community decide if
> it is useful or accurate.
> That's what the Internet is about, right?  Freedom to say any damn thing
> you wish, regardless of accuracy.  You are supporting free speech,
> that's a good thing, right?  BTW, all the people who say you are going
> about things wrong are just plain dumb, don't let their @openbsd.org
> e-mail addresses fool you.  E-mail can be easily spoofed.  Or they are
> trying to repress you.
>
> BTW: The more people you can get irate about your article and tell you
> so publicly on the mail lists (quoting the link to your article), the
> higher it will be in Google's rankings, permitting more people to find
> your wisdom!
>
>
> 6) Good formatting and pretty graphics mean more than actual content.
> Obviously, if your page LOOKS good, it must be good.  Complex things
> like CSS and browser-specific tricks are great!  Compared to the lame
> OpenBSD website, you will look like an absolute authority!
>
>
> 7) When you don't know what is going on, just tell everyone to do what
> got things to (sorta) work for you.  Don't waste time by researching
> your topic completely, or privately asking people in-the-know to verify
> key facts.
> The difficulty is clearly the result of the sloppy work of the OpenBSD
> developers.  Acknowledging your ignorance of a topic clears your
> conscience.  Just say, "I don't understand this, but it worked for me,
> so everyone should do this".
>
>
> 8) If you got the thing to work, you are qualified to write a HOWTO.
> The more you investigate something, the more annoying issues and special
> cases (like maintainability) come up, so don't waste your time.
>
>
> 9) An hour or two is sufficient to spend writing a HOWTO.
> Anything more than that is just wasting your time.  The reader will
> figure out the things you glossed over.  They were doing that before you
> came along, you are helping them, so this is a net improvement, right?
>
>
> 10) Demand that it be put on the OpenBSD website.
> Hey, if they don't like it, that can make the tiny little changes
> needed.  After all, didn't Thomas Edison say "Genius is one percent
> perspiration and ninety-nine percent inspiration"?  You provided the
> inspiration, they can do the one percent perspiration, right?  Since
> they are an open source project, and they do work for free, you have
> every right to demand they adopt your recommendations, after all, they
> have no clear direction without you.
>
>
> Ah, you will note that I failed my own list here, as I called this a
> HOWTO, but provided way too much explanation about why you should follow
> these tips.  Hey, writing sucky documentation is a difficult skill!
>
>
> (hopefully, the tongue-in-cheek (or head-in-toilet) nature of the above
> was obvious.)
>
> Nick.

That's just true. Nothing else.

Am i allowed to publish this on on a website of mine?

Jonathan

--
 | /"\   ASCII Ribbon   | Jonathan Glaschke - Lorenz-Goertz-Stra_e 71,
 | \ / Campaign Against | 41238 Moenchengladbach, Germany;
 |  X    HTML In Mail   | jabber: [hidden email]
 | / \     And News     | http://jonathan-glaschke.de/

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Emil Henry Flakk
In reply to this post by Nick Holland
On 11/25/05, Nick Holland <[hidden email]> wrote:

> We've been seeing a curious number of people offering various kinds of
> documentation on various OpenBSD topics.
>
> Most of them are somewhere between minimally useful and outright
> destructive and foolish.  I think I've seen precisely one that is
> looking very promising...and that was sent to me privately, you haven't
> seen it yet.  Obviously, bad documentation is in style now.  However,
> people seem to be thrashing around on how to write bad documentation, so
> here are some tips based on experience with a number of recent
> submissions to misc@...
>
>
> 1) Distribute your document in PDF file format.
> Yes, the Web is based on HTML, but hey, it is your document, make it
> PDF!  There are at least a couple people who prefer that format (if all
> else fails, register a hotmail or yahoo e-mail address under another
> name, and say, "I prefer PDF!").  That way, people MUST add additional
> software to their system to read your document.  People won't be able to
> send you diffs, so you can say honestly, "I received no useful change
> suggestions to this document, it MUST be good!".  It also hides the fact
> that while you are claiming to be an OpenBSD expert, the only text
> editor/formatter you know how to use is MS Word.  A PDF creation program
> will hide that very effectively.
>
> Bonus points for formats that are more obscure, less portable, or
> require over 500M RAM to open a two page document.
>
>
> 2) Write it as a HOWTO.
> Your reader just wants to know how to do the task they have at hand.
> After all, we know they are just wanting to accomplish the task, put it
> on their resume, and be elsewhere by the time it blows up.  It won't be
> their problem by then, anyway!  There is only one way to do most tasks,
> those extra knobs are there and set wrong just to confuse the new user,
> no one actually uses them differently, EVERYONE does things just like
> you suggest.  Theo delights in adding extra "knobs" to OpenBSD and
> making sure they are set incorrectly.  Rumors that he actively removes
> nonsense options are completely untrue.
>
> No one cares about life-cycle-related issues like upgrades or recovering
> from system failures or disasters.
>
> Besides, it is funny to watch people for whom English is not their first
> language think "howto" is a valid English word, and is often used with a
> question mark at the end ("Howto get my mouse working?"), as a
> replacement for "how do I ...?".
>
>
> 3) Write it for an older release.
> 3.8 was only just shipped, there are surely more 3.7 or 3.6 users that
> could benefit from your writing then there are 3.8 users, right?  The
> fact that improvements in the most recent release make much of your work
> incorrect or less than ideal isn't your problem...
>
>
> 4) Publish it, let it rot.
> Don't waste time bringing/keeping your old documents up to date.  There
> are so many other things you could be doing, instead.  People will
> figure it out.  After all, books don't automatically update on your
> shelf, why should a web page be any different?  Besides, PDF files are a
> pain to edit, and this way, you don't have to keep track of where you
> left the original source.
>
>
> 5) Write a rough draft, put it on misc@, and let the community decide if
> it is useful or accurate.
> That's what the Internet is about, right?  Freedom to say any damn thing
> you wish, regardless of accuracy.  You are supporting free speech,
> that's a good thing, right?  BTW, all the people who say you are going
> about things wrong are just plain dumb, don't let their @openbsd.org
> e-mail addresses fool you.  E-mail can be easily spoofed.  Or they are
> trying to repress you.
>
> BTW: The more people you can get irate about your article and tell you
> so publicly on the mail lists (quoting the link to your article), the
> higher it will be in Google's rankings, permitting more people to find
> your wisdom!
>
>
> 6) Good formatting and pretty graphics mean more than actual content.
> Obviously, if your page LOOKS good, it must be good.  Complex things
> like CSS and browser-specific tricks are great!  Compared to the lame
> OpenBSD website, you will look like an absolute authority!
>
>
> 7) When you don't know what is going on, just tell everyone to do what
> got things to (sorta) work for you.  Don't waste time by researching
> your topic completely, or privately asking people in-the-know to verify
> key facts.
> The difficulty is clearly the result of the sloppy work of the OpenBSD
> developers.  Acknowledging your ignorance of a topic clears your
> conscience.  Just say, "I don't understand this, but it worked for me,
> so everyone should do this".
>
>
> 8) If you got the thing to work, you are qualified to write a HOWTO.
> The more you investigate something, the more annoying issues and special
> cases (like maintainability) come up, so don't waste your time.
>
>
> 9) An hour or two is sufficient to spend writing a HOWTO.
> Anything more than that is just wasting your time.  The reader will
> figure out the things you glossed over.  They were doing that before you
> came along, you are helping them, so this is a net improvement, right?
>
>
> 10) Demand that it be put on the OpenBSD website.
> Hey, if they don't like it, that can make the tiny little changes
> needed.  After all, didn't Thomas Edison say "Genius is one percent
> perspiration and ninety-nine percent inspiration"?  You provided the
> inspiration, they can do the one percent perspiration, right?  Since
> they are an open source project, and they do work for free, you have
> every right to demand they adopt your recommendations, after all, they
> have no clear direction without you.
>
>
> Ah, you will note that I failed my own list here, as I called this a
> HOWTO, but provided way too much explanation about why you should follow
> these tips.  Hey, writing sucky documentation is a difficult skill!
>
>
> (hopefully, the tongue-in-cheek (or head-in-toilet) nature of the above
> was obvious.)
>
> Nick.
>
>

This should be added to the OpenBSD FAQ ASAP.

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

frantisek holop
hmm, on Sat, Nov 26, 2005 at 01:55:33AM +0100, Emil Henry Flakk said that
> On 11/25/05, Nick Holland <[hidden email]> wrote:
<snip Nick for now>
> This should be added to the OpenBSD FAQ ASAP.

not it shouldn't.  and maybe tongue in cheek but quite rude.

it contains a lot of flame and Nick should at least spellcheck
for the subject if nothing mor[sic] ;-)


> > 1) Distribute your document in PDF file format.

Nick's hate against pdf clouds his reason apparently.
pdf is a perfect format for technical documentation and
papers.  go and shout at people who publish their paper
in .ps and .pdf .  having said that i don't agree with
publishing _only_ in .pdf . all the formats have their use.


> > Besides, it is funny to watch people for whom English is not their first
> > language think "howto" is a valid English word, and is often used with a
> > question mark at the end ("Howto get my mouse working?"), as a
> > replacement for "how do I ...?".

making fun of people's language abilities is quite rude.
you misspelled the subject, how does that shine for a native speaker?
and does that make you stupid?  of course not.  just a simple mistake.

> > 6) Good formatting and pretty graphics mean more than actual content.
> > Obviously, if your page LOOKS good, it must be good.  Complex things
> > like CSS and browser-specific tricks are great!  Compared to the lame
> > OpenBSD website, you will look like an absolute authority!

what a beautiful argument.  is css complex for you?  am truly sorry for that.

everybody knows that openbsd is famous for its code quality.
does that mean that their pages must be ugly?  of course not.
sometimes it almost looks like people here take pride in
just how ugly the openbsd site is.  yes it is.  of course
that's subjective and if nothing else, serves its mission
(give information) 100%.  but that doesn't mean it must hurt
the eye.  there are people here at misc@ who work with
typography and graphics and so on (raise your hand please),
and i have a feeling they don't agree that openbsd must have
debian-ugly pages made by c hackers in 1995 who hate html
and think "design" is for pussies.

and the signal from the great hackers is that they don't care
about design at all, so nobody will even try.  but that's
fine, i am not really complaining.  but you know what,
i will propose one shortly just in spite.  i will write history.


and yes, documentation _can_ be nice and it's not a sin.

and no, the pages do not validate.  can follow hundreds
of standards in the source tree but can't follow 2-5
(depending on what you do) with (x)html.



where are my patches?

http://marc.theaimsgroup.com/?l=openbsd-bugs&m=102508555325610&w=2

apparently Nick is not too interested in validation but don't worry,
i will send those patches anyway.


> > Ah, you will note that I failed my own list here, as I called this a
> > HOWTO, but provided way too much explanation about why you should follow
> > these tips.  Hey, writing sucky documentation is a difficult skill!
> >
> > (hopefully, the tongue-in-cheek (or head-in-toilet) nature of the above
> > was obvious.)

and soooo encouraging for the future authors to be.


like really Nick, i understand your frustration, but have you
ever heard "the road to hell is paved with good intentions"?

people learn and hopefully realize their mistakes.
but not because you are making them ridiculous.

-f
--
experience is nothing but a lot of mistakes.

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

J Moore
On Sun, Nov 27, 2005 at 01:21:47AM +0100, the unit calling itself frantisek holop wrote:

> and i have a feeling they don't agree that openbsd must have
> debian-ugly pages made by c hackers in 1995 who hate html
> and think "design" is for pussies.

Ha! I like that line :) ...actually, I love it!

Right on, dude! Drop the hammer on that Grinch  :)

Jay

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Darrin Chandler
In reply to this post by frantisek holop
frantisek holop wrote:

>Nick's hate against pdf clouds his reason apparently.
>pdf is a perfect format for technical documentation and
>papers.  go and shout at people who publish their paper
>in .ps and .pdf .  having said that i don't agree with
>publishing _only_ in .pdf . all the formats have their use.
>  
>
I wouldn't presume to speak for Mr. Holland, of course. But I've raised
the pdf issue here a couple of times lately. I *don't* hate pdf. What I
object to is inapproriate use. Why the hell would you type out a text
document and then make it available as pdf only? No fancy formatting, no
graphics, no layout, just text. That's the kind of thing I've been
seeing in pdf. It's just stupid.

The IRS making tax forms available as pdf is *perfect* usage. People
making papers published in print magazines available online in pdf is
great. Using pdf as a uber cool, k-rad mechanical typewriter is braindead.

--
Darrin Chandler
[hidden email]
http://www.stilyagin.com/

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Bill Chmura-2
On Sat, 26 Nov 2005 21:16:17 -0700
Darrin Chandler <[hidden email]> spake:

> frantisek holop wrote:
>
> >Nick's hate against pdf clouds his reason apparently.
> >pdf is a perfect format for technical documentation and
> >papers.  go and shout at people who publish their paper
> >in .ps and .pdf .  having said that i don't agree with
> >publishing _only_ in .pdf . all the formats have their use.
> >  
> >
> I wouldn't presume to speak for Mr. Holland, of course. But I've raised
> the pdf issue here a couple of times lately. I *don't* hate pdf. What I
> object to is inapproriate use. Why the hell would you type out a text
> document and then make it available as pdf only? No fancy formatting, no
> graphics, no layout, just text. That's the kind of thing I've been
> seeing in pdf. It's just stupid.
>
> The IRS making tax forms available as pdf is *perfect* usage. People
> making papers published in print magazines available online in pdf is
> great. Using pdf as a uber cool, k-rad mechanical typewriter is braindead.
>

Well, PDF versions of text only files eliminate that whole nasty
win/unix cr/lf issue...

(Joking of course)


> --
> Darrin Chandler
> [hidden email]
> http://www.stilyagin.com/
>


--

Bill Chmura
Director of Internet Technology
Explosivo ITG
Wolcott, CT

p: 860.621.8693
e: [hidden email]
w. http://www.explosivo.com

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

bofh-6
In reply to this post by Darrin Chandler
On 11/26/05, Darrin Chandler <[hidden email]> wrote:
>
> I wouldn't presume to speak for Mr. Holland, of course. But I've raised
> the pdf issue here a couple of times lately. I *don't* hate pdf. What I
> object to is inapproriate use. Why the hell would you type out a text
> document and then make it available as pdf only? No fancy formatting, no
> graphics, no layout, just text. That's the kind of thing I've been
> seeing in pdf. It's just stupid.



Still better than a screen shot of the text, in a pdf.

And I learnt a new thing the other day, from a partner company's tech
support.  "tracert" (I know, I know), is "trace-report".

-Tai

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Jonathan Glaschke
In reply to this post by frantisek holop
On Sun, Nov 27, 2005 at 01:21:47AM +0100, frantisek holop wrote:
> what a beautiful argument.  is css complex for you?  am truly sorry for
that.

>
> everybody knows that openbsd is famous for its code quality.
> does that mean that their pages must be ugly?  of course not.
> sometimes it almost looks like people here take pride in
> just how ugly the openbsd site is.  yes it is.  of course
> that's subjective and if nothing else, serves its mission
> (give information) 100%.  but that doesn't mean it must hurt
> the eye.  there are people here at misc@ who work with
> typography and graphics and so on (raise your hand please),
> and i have a feeling they don't agree that openbsd must have
> debian-ugly pages made by c hackers in 1995 who hate html
> and think "design" is for pussies.
>
> and the signal from the great hackers is that they don't care
> about design at all, so nobody will even try.  but that's
> fine, i am not really complaining.  but you know what,
> i will propose one shortly just in spite.  i will write history.
>
>
> and yes, documentation _can_ be nice and it's not a sin.
>
> and no, the pages do not validate.  can follow hundreds
> of standards in the source tree but can't follow 2-5
> (depending on what you do) with (x)html.
>
> where are my patches?
>
> http://marc.theaimsgroup.com/?l=openbsd-bugs&m=102508555325610&w=2
>
> apparently Nick is not too interested in validation but don't worry,
> i will send those patches anyway.

The Web is against good design.  You can see this by looking at the most
people's choice of browser.  Bad web browsers are the biggest problem in
creating a good looking website.  I now nobody using CSS who takes care
of ie 4 or older.  Nearly nobody is actually taking care of ie 5/5.5,
too, but thats default in windows 2000.

So you have to get tricky - ever seen the new freebsd website:

        <div id="CONTENT">
          <div id="FRONTCONTAINER">
            <div id="FRONTMAIN">
              <div id="FRONTFEATURECONTAINER">
                <div id="FRONTFEATURELEFT">
                  <div id="FRONTFEATURECONTENT">

Yeah, thats good design.  That's a div war.
The wasted space at the left and right even not mentioned.
I was subscribed to freebsd-www@ during the change of their site.
Can you image how many people complained about problems in viewing?
Just too many.

HTML and CSS are designed to be platform independend, but you hardly
find any good-looking sites that take care of this advantage.

What a lot of people forget is that having a good website means having
content, not having a good design.

So, we are talking about a better, fresh and modern design using XHTML
and CSS.  We can't use XHTML 1.1 (which is the latest web standard)
because most people's browser can't handle it, thats the first limitation
because of a broken web.  We can't use modern and complex CSS, too,
because of the same reasons.  Beeing modern is not supported by the web.

Thing about all the translaters who have to adapt the new design.
That was sure not what they thought about when they became a translator.

And if we talk about a new design - why don't we talk about generating
sites with a modern scripting language?  That's only the next step, but,
who wants that?  Who needs that?  Who wants to implement it?

If there is only one person who has problems to view the content because
of a new and tricky design, than the new design was a step in the wrong
direction. Thats my opinion.

Jonathan

PS: If we change now to a modern design, how long would is last until
the first person thinks about a flash movie on the starting page?

--
 | /"\   ASCII Ribbon   | Jonathan Glaschke - Lorenz-Goertz-Stra_e 71,
 | \ / Campaign Against | 41238 Moenchengladbach, Germany;
 |  X    HTML In Mail   | jabber: [hidden email]
 | / \     And News     | http://jonathan-glaschke.de/

[demime 1.01d removed an attachment of type application/pgp-signature]

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

frantisek holop
hmm, on Sun, Nov 27, 2005 at 10:29:27AM +0100, Jonathan Glaschke said that
> The Web is against good design.  You can see this by looking at the most
> people's choice of browser.  Bad web browsers are the biggest problem in
> creating a good looking website.  I now nobody using CSS who takes care
> of ie 4 or older.  Nearly nobody is actually taking care of ie 5/5.5,
> too, but thats default in windows 2000.

there are ways to get this (mostly) right.
there are great pages which show perfectly in lynx/links
and have maybe a couple of div's inside.

css and xhtml does not exclude simplicity.
one can make beautiful (eye pleasing) sites
with using 4 div's (not nested too).


also, one cannot stick to the old technologies all the time.
the project is overall bold in scratching old stuff (telnetd,
rlogin and friends).  but with html, it's back in the 90's.


> So you have to get tricky - ever seen the new freebsd website:
>
>         <div id="CONTENT">
>           <div id="FRONTCONTAINER">
>             <div id="FRONTMAIN">
>               <div id="FRONTFEATURECONTAINER">
>                 <div id="FRONTFEATURELEFT">
>                   <div id="FRONTFEATURECONTENT">

so what if there are divs?  should be tables or what?
the new site looks just great in links/lynx btw.
and it looks (quite) good in modern browsers _also_
so who is robbed of the precious info inside?


> What a lot of people forget is that having a good website means having
> content, not having a good design.

yes, and what a lot of people forget is that having a good website means
having nice layout too.

so how about both?

it's like saying a good book is only the good content.
yeah, and try to read it if it's typeset in comic sans ms.


> So, we are talking about a better, fresh and modern design using XHTML
> and CSS.  We can't use XHTML 1.1 (which is the latest web standard)
> because most people's browser can't handle it, thats the first limitation

where's your numbers?  what's most people?  "most people" on the web
these days is some version of IE.  i thought ie supports xhtml.

> And if we talk about a new design - why don't we talk about generating
> sites with a modern scripting language?  That's only the next step, but,
> who wants that?  Who needs that?  Who wants to implement it?

could be, doesn't have to be.  certainly would save a lot time
to the devs which could be used for something else.  couldn't
cvs it directly though (the content).


> If there is only one person who has problems to view the content because
> of a new and tricky design, than the new design was a step in the wrong
> direction. Thats my opinion.

well, good look serving all the people.
come on, you know that you can't please everyone, don't you?
_that_ is precisely what openbsd is about.  it never aimed
pleasing _everyone_


Theo is man of principles, i have seen that proven many times.
but the site is somehow a sad exception to his principles.
it's just not a priority and i can live with that.

> PS: If we change now to a modern design, how long would is last until
> the first person thinks about a flash movie on the starting page?

i wish people would not be such extremist on this list..

do not insult me with flash, earthling.

-f
--
user: a technical term used by computer pros.  see idiot.

Reply | Threaded
Open this post in threaded view
|

Re: HOTO Write bad documentation

Jonathan Glaschke
On Sun, Nov 27, 2005 at 01:39:18PM +0100, frantisek holop wrote:

> hmm, on Sun, Nov 27, 2005 at 10:29:27AM +0100, Jonathan Glaschke said that
> > The Web is against good design.  You can see this by looking at the most
> > people's choice of browser.  Bad web browsers are the biggest problem in
> > creating a good looking website.  I now nobody using CSS who takes care
> > of ie 4 or older.  Nearly nobody is actually taking care of ie 5/5.5,
> > too, but thats default in windows 2000.
>
> there are ways to get this (mostly) right.
> there are great pages which show perfectly in lynx/links
> and have maybe a couple of div's inside.
>
> css and xhtml does not exclude simplicity.
> one can make beautiful (eye pleasing) sites
> with using 4 div's (not nested too).
>
that would be great, but thats an exception.
>
> also, one cannot stick to the old technologies all the time.
> the project is overall bold in scratching old stuff (telnetd,
> rlogin and friends).  but with html, it's back in the 90's.
>
telned is no longer in source.

>
> > So you have to get tricky - ever seen the new freebsd website:
> >
> >         <div id="CONTENT">
> >           <div id="FRONTCONTAINER">
> >             <div id="FRONTMAIN">
> >               <div id="FRONTFEATURECONTAINER">
> >                 <div id="FRONTFEATURELEFT">
> >                   <div id="FRONTFEATURECONTENT">
>
> so what if there are divs?  should be tables or what?
> the new site looks just great in links/lynx btw.
> and it looks (quite) good in modern browsers _also_
> so who is robbed of the precious info inside?
>
Do you think thats good code? That's just overkill because of broken
webbrowser. It's just pain in my eyes.

> > What a lot of people forget is that having a good website means having
> > content, not having a good design.
>
> yes, and what a lot of people forget is that having a good website means
> having nice layout too.
>
> so how about both?
>
> it's like saying a good book is only the good content.
> yeah, and try to read it if it's typeset in comic sans ms.
>
that depends on how you look at it.  Comic Sans MS looks good, a good
readable font doesn't look good, but is usefull.  That's exactly my
problem with "modern design".  If you don't specify a font in a web page
then the result is a good readable and well sized font.

>
> > So, we are talking about a better, fresh and modern design using XHTML
> > and CSS.  We can't use XHTML 1.1 (which is the latest web standatrd)
> > because most people's browser can't handle it, thats the first limitation
>
> where's your numbers?  what's most people?  "most people" on the web
> these days is some version of IE.  i thought ie supports xhtml.

XHTML 1.1 must be shipped as application/xhtml+xml.  IE can't handle this
and ask the user (or the "idiot", as you signature says ;) where to save this
file.  That's not a real problem since you can use xhtml 1.0 but that
shows how broken things are.

>
> > And if we talk about a new design - why don't we  talk about generating
> > sites with a modern scripting language?  That's only the next step, but,
> > who wants that?  Who needs that?  Who wants to implement it?
>
> could be, doesn't have to be.  certainly would save a lot time
> to the devs which could be used for something else.  couldn't
> cvs it directly though (the content).
>
>
> > If there is only one person who has problems to view the content because
> > of a new and tricky design, than the new design was a step in the wrong
> > direction. Thats my opinion.
>
> well, good look serving all the people.
> come on, you know that you can't please everyone, don't you?
> _that_ is precisely what openbsd is about.  it never aimed
> pleasing _everyone_
>
>
> Theo is man of principles, i have seen that proven many times.
> but the site is somehow a sad exception to his principles.
> it's just not a priority and i can live with that.
>
> > PS: If we change now to a modern design, how long would is last until
> > the first person thinks about a flash movie on the starting page?
>
> i wish people would not be such extremist on this list..
>
> do not insult me with flash, earthling.
>
> -f
> --
> user: a technical term used by computer pros.  see idiot.
>

I'm not against xhtml, but like easy things. Putting 100 divs in one
file is no solution.

Jonathan

--
 | /"\   ASCII Ribbon   | Jonathan Glaschke - Lorenz-Goertz-Stra_e 71,
 | \ / Campaign Against | 41238 Moenchengladbach, Germany;
 |  X    HTML In Mail   | jabber: [hidden email]
 | / \     And News     | http://jonathan-glaschke.de/

[demime 1.01d removed an attachment of type application/pgp-signature]

123