Slashdot Mirror
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?"
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?
#DeleteChrome
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.
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.
Also, the full text should remain available in plain ASCII. Just my $0.02 worth. Thanks for asking!
If all this should have a reason, we would be the last to know.
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
Use my link above, or to view my server, NeoThermic.com
I can't remember who said that long ago, but it is an important axiom.
:-) ) 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.
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
Cheers!
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.
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.
Online citizen journalism from the inner city: The View From The Ground
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.
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)
-- If you try to fail and succeed, which have you done? - Uli's moose
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.
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.
Don't blame me, I didn't vote for either of them!
Hard coding a paticular style sheet into HTML - even if that HTML happens to be generated - kind defeats the purpose, no?