CSS for the LDP?

Saqib Ali asks: "Over at The Linux Documentation Project there is a lengthy discussion going on about whether to use CSS (Cascading Style Sheets) to improve the presentation of the documents. I support the use of CSS to improve the image/formatting of the document, and improve readability. I understand that content is more important than the presentation, but it can't hurt to improve both. There are others who think we should not get involved the presentation layer, and mainly concentrate on the content. Since, most Slashdot readers are Linux users, and might have visited the LDP once or twice, I would like to poll them on what they think about implementing and using nice CSS for the documents on the Linux Document Project website. I've written a CSS for this purpose that is available here, and some sample documents available in this weblog. Any thoughts? Any pros and cons on using CSS to improve presentation?"

Comments

What?

[93 Escort Wagon]

I know this is a bit of a tangent, but...

"Most Slashdot readers are Linux users" - seriously? I know there's a strong anti-MS contingent, but this can't be true. Is there data to back that up or are you just talking out of your, er, hat?

Re:What?

[Anonymous Coward]

"Most Slashdot readers are Linux users" - seriously? I know there's a strong anti-MS contingent, but this can't be true. Is there data to back that up or are you just talking out of your, er, hat?

Umm, depends what you mean by "linux users". I recall an analysis of the browsers used by slashdot readers to browse slashdot, and most of them use windows to read slashdot.

Is browsing a website that runs on linux enough to be a "linux user"? I don't think so.

Do you get your email from an IMAP or POP server running linux? I don't think that makes you a linux user.

I'd say you're a linux user if you use a shell account or X11 windows/KDE/Gnome/whatever on linux some of the time. I think a majority of slashdot readers are linux users by that criteria.

Re:What?

[tverbeek]

Well, in the sense that we're all Sendmail users and Apache users and BIND users (i.e. we interact with them on a day-to-day basis, even if we don't run them on our own systems), /.ers are (by definition) all Linux users (and Perl users). Of course that makes most of us Windows users as well, since it's hard to get through the day without hitting some site running IIS or Exchange.

Personally, I think it's silly that people try to pigeonhole me as a [insert OS here] user since I use (i.e acting as a local or authenticated remote operator or user of) anywhere from 4-8 different OSes over the course of a typical week.

Re:What?

[bcrowell]

Considering that Linux systems account for somewhere on the order of 0.5% of all desktop machines, it's not realistic to expect the majority Slashdot users to be running Linux on the machine they're slashdotting with. If even 20% of Slashdot users are slashdotting using Linux, that's an amazing triumph.

An even more amazing triumph would be if Linux's share of desktop systems could grow by an order of magnitude, to some incredibly large figure like 5%. But I'm not holding my breath, because 5% is a lot more than the fraction of the population who are interested enough in computers to take the trouble to use Linux.

Oh, and just so you know where I'm coming from, I'm posting this from a FreeBSD box :-)

Re:What?

[aulendil]

But ... most of my Slashdot time is done in work where they make me use Win XP. So how accurately am I represented in those stats?

Since you yourself say that you mostly read Slashdot in Win XP, I would say your quiet accurately represented in those stats.

Presentation Problem to be solved?

[Thanatopsis]

Exactly what presentation problem are you trying to solve? Make it look prettier? The UI is pretty solid. Just wanting to change the presentation layer without understanding what you are trying to achieve for the user is silly.

Why should it be opposed?

[metalhed77]

It would be trivial to write a CGI script that would simply include, or not include the link to the CSS for each document. Assuming of course that all these documents are in XML (docbook?) format to begin with.

xml

[mastergoon]

If you are going to go through all that work to reformat the documents, it seems more reasonable to go to an XML/XSLT system. For documentation projects XML is the way to go, so it can be viewed great in many applications.

Before you start whining that "it wont work in my browser," remember, there are several solution where the stylesheet is applied server side, and the page can be servered as plain old html.

Silly

[sethadam1]

Isn't this kind of silly? Why would we the Linux community actively choose to NOT use stylesheets? They're not complex and they're widely supported now. Only this community of emacs users at GUI-less workstations users would think it better to not use CSS. I see refusing their introduction as actively alienating users by refusing to implement anything that could possibly be considereed "eye candy."

I'm sure someone will mod this down as flamebait, but it's not meant to be. Truly, this is one of those times I find myself not so surprised that Microsoft retains so many customers - because you gotta sell the sizzle with the steak.

Re:Silly

[Nailer]

Why would we the Linux community actively choose to NOT use stylesheets?

We wouldn't. Chances are:

• The poster is on a mailing list with soemone who doesn't like CSS for no reason other than they don't understand it
  
• The poster has submitted the concept to Slashdot so that the project can see that this person is a tool
  

Why even ask?

[chuyskywalker]

Of course they should!

CSS doesnt touch the content of a document at all - that's the whole point of it. You can "pretty up" a document without needing to redo all the content's code. In addition, no one doing to the documenting needs to worry about anything new - they just continue as always. The "extra" download can be turned off in cool browsers so that its formatted normally - heck, even a fancy JavaScript button can be set up to use different (or no!) style sheets.

So - Better appearance, negligable performance hit, backwards compatable, no change in article (html) formatting, and zero drawbacks. Why would they not put CSS into action? Even basic CSS can do wonders.

Consistency, please

[Rick the Red]

If LDP goes with CSS, it should be one CSS for all the documents. I'd hate to see each document author do their own (different) style sheet.

Also, the full text should remain available in plain ASCII. Just my $0.02 worth. Thanks for asking!

Re:Consistency, please

[Tin Foil Hat]

I think he meant not having the documentation authors be able to specify CSS files for their own documents. That's totally different than what you are suggesting, which is user-selectable alternate style sheets.

Both are exellent ideas. However, in order to do this properly, the LDP would have to also create a style guide for their documentation authors so that they can check their HTMl against it.

Perhaps having a group available to edit mark-up for the authors would also be a good idea. These people would be volunteers, and would not necessarily be among the same group as the authors. The downside to this is that it creates added overhead to the document submission process, which results in longer delays to publishing. That is not to say, however, that it should not be considered. Sufficient planning could overcome such obstacles rather easily.

After reviewing the samples.

[Morologous]

I'd have to say that I'm all for the CSS update. I was a little ambivalent at first, as I've never really payed any attention to the presentation of the documents before. But the simple, content oriented style in use in the examples makes the documentation all the more readable. And if the style makes it easier and more accessible for people, then I say go for it. The more people who read your documentation the better, in any case.

Re:why not?

[NeoThermic]

Presentation, readablilty and understanding is what makes documentation usable.

This includes formatting, and visual output.

If content is controled by CSS, then in theory, the content can be ammended as needed, with those in charge of presenting it not interfering with the actual documentation. This could lead to less time to prepare content as you stated.

Remember, what makes the Microsoft KB almost un-usable is its presentation. What makes php.net's documentation usable is its presentation.

Guess who has got it right, and who hasn't.
Guess also who uses proper presentation and who doesn't. Compare.

NeoThermic

Lack of CSS standardization

[inphinity]

As I see it, there is a huge roadblock standing in the way of any organization using CSS at all, and that's a lack of standards.

Although there exists a defined template for the behaviour and appearance of each CSS element in the specification, there does not exist a browser that is fully CSS compliant. In fact, of all of them, Microsoft is the worst.

Now, the biggest argument here is that anybody using Linux will be using anything BUT MS products, but you're still not out of the woods yet. For, even between two browsers that are fairly good with CSS standardization, i.e. Apple's Safari and Mozilla's Firefox, you have not just suble behaviour differences, but also large gaps in the way each broswer handles such elements as left, right and relative positioning constants.

If all browsers had at least (somewhat) decent CSS compatibility, then I'd say yes, absolutely use it, because CSS has the potential to really imporove the layout of any site with minimal effort.

Perception is more important than reality.

[steve buttgereit]

I can't remember who said that long ago, but it is an important axiom.

Many readers will tune out or find it even daunting to jump into a document that doesn't make an effort to present itself well. Even when the content is top notch, weak presentation will leave a poor first impressions placing the author on the defensive from the get-go. That's not to say good presentation will save a bad document... but every little bit helps!

If using CSS makes the documentation look more professional, more organized, easier on the eyes, and more consistient in presentation I say go for it. Just don't fall into the mistake of overdoing it and continuously changing the presentation... then effort will be wasted.

One final point: corporations (including Microsoft :-) ) pay lots of money to be sure documentation is clear and attractive. Without commenting on success, they do spend those dollars and make the effort for a reason.

Cheers!

Re:Excellent idea.

[bbsguru]

The idea is the thing, right? It's all about the content after all..

No, it isn't. It's also about communication, and to the extent that better presentation helps communicate more clearly, CSS should be used. The best ideas that are never heard matter not.

Don't let the presentation get in the way of the content? Exactly. But don't let the lack of presentation take away from it either.

Re:Excellent idea.

[Anonymous Coward]

It's not a matter of "getting involved in the presentation layer,"

Sure it is -- CSS allows the webdesigner to force you to read his site using an 8 pt Comic Sans font.

I have no idea why that is necessary for things like simple Linux HowTos. Just set the font you want in your browser. This is not a complex site.

Most linux users won't be using IE

[Anonymous Coward]

They'll be using something with a pretty good CSS implementation like Mozilla.

Printing: Another Advantage of CSS

[TheViewFromTheGround]

I think it goes without saying that Linux folks should embrace CSS. It's sort of a no-brainer. That being said, another advantage is style-sheets for different media. In particular, LDP pages are likely to be printed (I printed one the other night for a Linux install where I didn't have a live Internet connection), and even with all the problems, a smart designer can make very nice print stylesheets that use serif fonts (not so good on screen, very good on paper from a readability standpoint), add banners that print on each page, etc. This assumes a well-structured document that the CSS is styling, but that's a big advantage.

Docs should be semantically marked up anyways

[count0]

I think any CSS detractors are missing the point - docs should be marked up consistently, with H1, H2, etc. Particular semantic types (like author) could be added as styles for particular tags e.g. Adding CSS would be relatively simple on top of semantically structured docs.

Re:Docs should be semantically marked up anyways

[wheany]

I knew there had to be someone who had some sense left. This was the real point from the start. Assuming the documentation is already in html, if you can't just "drop in" some CSS to make it prettier, there is something wrong with the markup.

And if that's the case, you need to fix the html first.

Priorities ?

[Prop]

There's nothing wrong with CSS in and of itself, but the because issue facing the LDP is NOT how they should handle presentation. It's the seriously outdated content in many HOWTOs and FAQs. If I had a say, that's where I'd "vote".

IMHO...

[ioexcptn]

CSS & LDP, PDQ!

No, but really, it is always a good idea to make docs user-friendly, especially when the Linux community as a whole is trying to recruit the troves of Windows users out there. Anything to make user experience more friendly shouldnt be overlooked.

Who among us here doesnt remember that first RFC that we gasped in confusion at? And the fact that it was entirely in Courier 10 didnt help ;)

Readability!!!!

[moosesocks]

When I first used gentoo linux, I was most impressed by the quality of the documentation provided.

And then I realized. It wasn't necessarily high qualty nor at the time did it contain better content than the guides for Debian and Red Hat. It was presented in a much cleaner format using CSS and a nice clean layout. Since then, the quality of the gentoo documentation has only improved.

Compare this gentoo page with this TLDP page.

See the difference? They both contain useful information. The TLDP documentation makes me feel like i'm reading a legal document. Blegh! The gentoo document is much less harsh on the user.

This is scary, considering that gentoo is widely considered one of the most difficult of the linuxes to use, as it contains absolutely no installer. Thanks to the clear documentation, I actually perfer the gentoo installation process over fedora's, as it's easy (thanks to the documentation), and gives me a tremendous amount of control. I think this fact can only be capitalized by the fact that I use a mac 95% of the time as my desktop machine.

Please... add some color. It helps. Lots of people are visual learners. It just so happens that most linux users aren't (Reading a monotonous 26-page manpage on ls of all things makes me want to gouge my eyes out)

Re:Readability!!!!

[Anonymous Coward]

I strongly agree with parent. Gentoo's docs make extensive use of colour, highlighting blocks, etc in order to improve readability and make important parts obvious. Reading and following them is very easy (just try having a browse through one of their guides, for example the ALSA one, to see what I mean). The importance of colour should never be underestimated in documentation, particularly documentation that can be considered dull and monotonous, as most of the linux howtos can. Sure, they arn't meant to be exciting reading but it is important to have easy readability rather than a huge chunk of plain black text when you're looking for important info.

I also agree on prefering the gentoo installation process. :) I found it much easier than any other I've tried (redhat, mandrake and debian).

Answered your own question?

[PCM2]

There are others who think we should not get involved the presentation layer, and mainly concentrate on the content.

Um, isn't that what CSS is for?

Seriously, what could the cons possibly be?

Re:Great examples as to why they SHOULD NOT use CS

[Cameroon]

Gee, that's funny, I could read it perfectly fine in IE 5.2 on Mac OS 10.3. Wonder why that might be. Oh, yes, I turned off CSS in the browser.

Normally I wouldn't post a reply to something like this, but the whole shitty, breakable design that is so much of the web is in large part due to supporting pathetically old and broken browsers and proprietary extensions. NS 4 anyone?

Mac IE 5.2 did way better than previous Mac browsers with CSS but it is by no means some sort of quality benchmark. ON TOP OF WHICH, you could easily write CSS that does something to make a site look better, but is still simple enough for Mac IE 5.2. It's rather ridiculous to take a broken browser and say "look, I know it's borked but look, it doesn't render this site correctly". What makes this even better, is that the site is entirely usable because thankfully MS did include the ability to disable style sheets (or use your own) in Mac IE 5.2.

There's no reason not to use CSS unless it means that someone who would otherwise have been writing documentation is now writing CSS. I believe it more than likely, however, that there are people who would be willing to work on the CSS but who would otherwise not be involved in the project.

Content dammit!

[Brandybuck]

There's more than one person working on LDP, so do whatever you're best suited at. If that's CSS, then put in some CSS. On the other hand, if you were the only person working on it I would skip the CSS and put in some friggin content!

I'm a FreeBSD user who has to dabble in Linux from time to time. So every time I need some Linux info I go to LDP. What I generally find are horribly out of date HOWTO's and incomplete manpages. Quality content is lacking. For example, the XFree86-HOWTO was last updated September 2001. Maybe not a lot has changed since then, but considering the sparsity of information in this document, someone could have at least expanded a bit on several areas. Another example is ALSA. This was recently added to the 2.6 kernel, but the HOWTO was last updated November 1999!

So go ahead and work on your CSS. But find out who's in charge of content, and give them a swift kick in the butt!

p.s. Don't go too wild on the CSS. Make it use the standard DocBook-XSL produced HTML. For a good example see FreeBSD's stylesheet. It's not going to win any NEA grants, but it gives a consistant professional feel to all of the FreeBSD HTML docs.

To be quite frank - give me .txt

[arcade]

I used to love Linux howtos and faq's. They were great - a charm to read, just like RFCs.

Then they began to htmlize them, and I couldn't just less then any more. Which, quite frankly sucked.

Then they began to come in "chapters" instead of one giant file. Which, quite frankly, sucked even more.

I'm sure there's an option to get all the howtos and documentation in good old ascii out there _somewhere_, by the gods the LDP has made those more difficult to find.

And not, this is not an attempt to troll. It's an honest frustration. You cannot search a html document which contain 20 different html-files (one for each chapter) like youc an search a single .txt file.

CSS helps structure, too

[Doc Ruby]

The best use of CSS, other than offering an easy way out of spending time on formatting (in favor of time spent informing) is any consistent presentation of the documents. I want to learn LDP documentation structure once, so I can quickly look for author attribution, platform (version, distro, HW, etc) details, publication (relevance) date, and "related links" to projects, docs, presentations, discussions, etc. Using CSS will not only make that structure easier to produce and comply with, it will make it easier for me to read, and to discard inappropriate docs more quickly. It will also make indexing the docs for searching much more straightforward. Get right on that!

IE works just fine

[KalvinB]

I have the latest version of IE and those pages work just like they're supposed to.

Whining that IE 5.0 doesn't fully support CSS is just braindead. It's an old browser. MS has been working on compliance and updating their browsers. If you insist on using a broken version when fixed versions are available, that's your issue. Not Microsoft's.

IE 5.0 has been fixed to support lots of new things. And now it's called IE 6.0. What did the guy bitching about IE 5.0 seriously expect? That MS would make changes but keep the same version number?

"MS IE is not CSS compliant"

Which version? Apparently Mr 5.0 hasn't figured out that when MS puts out an update for IE it usually changes the version number. MS was obviously aware that 5.0 wasn't up to spec. So they patched it. The latest patch brings you up to 6.0. So if you're not keeping up with patches then you really have no place to bitch. They did obviously fix the problems. You just refuse to apply the patch(es).

Ben

Re:Done right, CSS can help multi-platform use.

[T-Ranger]

One would wonder why I cant just click on my Firefox stylesheet button and make the change from there.

Hard coding a paticular style sheet into HTML - even if that HTML happens to be generated - kind defeats the purpose, no?

my honest opinion

[Anonymous Coward]

This isn't intended as a flame or a troll, though it may be seen that way.

First of all, the one language that's going to really move Linux documentation forward isn't CSS. It isn't docbook, and it isn't XML or XSLT or texinfo or anything like that. It's English. Let's face it: lots of Linux documentation is poorly written. It doesn't just break grammar and style rules; it's intelluctually muddy, unclear, imprecise, and just hard to understand.

Honestly, if the Linux documentation people don't focus on promoting a good, clear expository writing style as their first priority -- which it obviously is not -- then I don't care if they hire a team of 1,000 super-talented typesetters and graphic artists to dress it up. Linux is a good operating system, and it has some good technology in it, but if I were writing a little summary of Linux, I'd put documentation under "minuses" and not "pluses".

(Which is not to say all other operating systems are better. Windows documentation seems to have a consistent style, but part of that style is dumbing things down enough that most of the useful information is removed.)

Re:What about Slashdot?

[LoveTheIRS]

As long as we can access the LDP from lynx I am happy

Re:What about Slashdot?

[Anonymous Coward]

Tables are for tabular data, not for layout.

Doesn't matter to me either way

[X-Nc]

I have nothing against presentation so if a decent css (and the one the original author did isn't bad at all) is used I would not be against it. I am more concerned with the information/content/data than the presentation of same, though. Keep it simple. Keep it clean. As long as those two criteria are met then I don't really care.

My main concern is...

[fyngyrz]

The worst sites for me are sites where I can't change the text size, and also sites where the width of the page has been predefined, even if I can change the text size. I stretch the browser window wide, and the stupid page locks at 640 or 800 pixels wide - at that time, I'd like to smack the page designer right upside the head.

Basic HTML pages don't seem to ever lock down text size (I'm not sure they even can - does anyone know?) and letting the page reach the width that the browser window is set to is a simple act of omission - just don't put a pixel width in any outer-level tables (assuming there are any tables), use percentages instead.

The very worst offending pages I run into all seem to be CSS-based; so while it certainly flexible, it is also a means by which pages can be made almost unusable. One of the reasons I prefer Mozilla Firefox is the ability to size text even on "locked" CSS pages (though I wish it could natively size images as well.) MS IE isn't nearly as friendly about this, though you can kind of hack it to work with the "Accessibility" settings. No big deal, I formatted my last XP system into a Linux machine a few weeks ago. :) But I still have to use IE at work, sometimes. The Windows Firefox isn't quite as clean. But I digress.

As you can probably tell, I'm a member of the crowd that thinks the user should always control the entire end presentation, and never, ever should the web site do so. The only thing that annoys me more than locked-format web pages are PDF pages, which are not only completely locked, they're overweight and massively sluggish compared to HTML - I have zero use for them.

So, as long as the CSS isn't used to enforce text size and/or width rules, I'm all for it.

But if either one of those capabilities goes away, for any reason, honestly, I'll probably stop visiting the site. My eyes are getting older a good deal faster than the rest of me is.

My .02

Use as alternate style sheet if necessary

[zonix]

The markup used for the LDP files is quite straigtforward and luckily stripped of any bloat like font tags and like, and as such I'm sympathetic to the idea of not getting involved with the presentation layer.

For most pages (ie. like /.) using CSS will greatly increase page load times when all the presentational deprecated markup is shed in favor of CSS. Much of the redundancy is gone after this treatment.

However, this is not the case with the LDP files as they are already stripped of any presentational information (*). Though, this is also an advantage in this case, as the markup then lends itself quite nicely to being used with CSS. It would still for the most part be for the eye-candy purposes (which is okay), and therefore my recommendation would be to provide the style sheets as alternate style sheets. People can choose one of the different looks if more style sheets are available, or by default stick to the tried and true look.

(*) However, when we already have this clear separation of content and presentation, it would still be possible for the doc writers to do their job like they're used to without worrying about presentation. And if I'm not mistaken, the documentation source is in docbook format - here they're not worrying about presentational stuff anyway. YMMV, of course.

z

Each page will have a different style sheet

[Animats]

There are a number of good reasons not to use style sheets. First, they introduce a dependence on directory structure. If we start seeing links like "../../../x11/styles" in documentation, something has gone wrong.

Second, getting different people to use the same style sheet on an open source project is tough. And if everybody has different style sheets, there's no point.

Third, unless everybody edits HTML with the same WYSIWYG editor, nobody will be able to use a WYSIWYG editor on the HTML. (Has anyone written an open-source Dreamweaver replacement yet?)

Re:Who uses IE for the mac anyway?

[I confirm I'm not a]

I'll second that, and add that in many cases CSS-based sites only work on IE because the developers jumped through hoops to make it so. There are numerous IE-specific hacks to stop IE from choking on CSS, even CSS1. Not that long ago /. looked at IE7, a style-sheet that brings IE6 upto an acceptable level of CSS compliancy. Hacks like this should not be necessary - it's not like MS are ignorant of standards that have, in some cases, been around since 1997.

Re:Done right, CSS can help multi-platform use.

[Uggy]

CSS can also help people think more about the actual structure of their documents. If we apply CSS to LDP, then someobody's got to standardize the structure across all the documents. Take a look at Gentoo. From day one, they have presented their documentation with data structure being the number one concern.

CSS are like writing a business plan. It gets you thinking about the nitty gritty details of your document and just like a business plan gets you thinking about details in your business.

Re:What about Slashdot?

[arodland]

Of course; the argument is that 99% of the things displayed in HTML tables aren't actually tabular.

Content first, THEN style!

[KevinDumpsCore]

I'm an Open Source documentation volunteer. My experience in the trenches reveals this: In order for technical documentation to be usable, it must be clear, complete, correct, and current.

Usable documentation then becomes great if it is also consistent. It's frustrating to see Open Source documentation projects like the LDP spending so much time on consistency when they haven't reached usability yet. Getting there is hard work, I know.