Booklets
|
| Author | Content |
|---|---|
| jacog Feb 03, 2009 4:54 AM EDT |
Welllll ok... here's a thought or two. Work with me. PREFACE: Ship these freaking things with a regular type of desktop enviroment that has not been 'tarded down, first of all. It's all fine explaining that a netbook is not intended to replace a laptop and that it's only meant for on-the-go net-ish things... but that's pointless unless this is explained to the customer buying it. THE THOUGHT: What Linux suffers from the most is a lack of good documentation. It's not good enough to just point a newbie user to help files, the web, man etc. I think if a user buys an out-of-the-box Linux machine, there should be some wee little dead tree added that covers the basics, and also serves to make it seem exciting. "User! Welcome to this exciting world of LinDistro. Here are some of the great features you will discover." And please try not to read that in the voice of Barney the Dinosaur. It should be a user manual that also serves as a marketing tool, to market the product that the user has already bought to the user. So, was thinking... perhaps some enterprising publisher could write and release a series of mostly white-label booklets that are grouped into several functions. Some covering very basic terminology. Some that are desktop environment specific. Some that are distro specific. Some more advanced. So vendor X, running distro Y on their pre-installed system, can pick out booklets A, J, F, and P... and bundle it with their sale, along with an additional booklet that's specific to their hardware. And there's no reason why these should not be free to download, free to reproduce. And perhaps also supplied in an interactive digital format, all with the same basic principles. Be informative. Be helpful. Be exciting. |
| land0 Feb 03, 2009 5:37 AM EDT |
This is a great idea. Ultimately the question is are you willing to head up such an effort? My experience has been that the biggest challenge that great ideas have is nobody seems to have enough free time to head them up and develop them. Not complaining just observing. I would like to invite you to post this on http://thetuxproject.com We could create a book project for you to work with. It may not come together overnight but then again who knows. Either way the bandwidth and space will be yours if you are interested. |
| jacog Feb 03, 2009 5:54 AM EDT |
Yah, I reeeally suck at follow-through. :) I have an infinite amount of ideas, but am unlikely to actually carry any of it to the finish line. But ok, will at least cross-post the idea. |
| ColonelPanik Feb 03, 2009 1:44 PM EDT |
Damn smart people I hang with here on LXer! jacog: Take the rest of the week off, you will not have a better thought! Thank you. land0: Don't let it die. Good project. |
| jacog Feb 03, 2009 1:58 PM EDT |
Argh! I thought I'd just put it out there, and see if anyone rolls with it, but now you got my mind going in all kinds of directions. - The documentation should be maintained online and visible at all times. - Content stored in a digital format that can easily be output as HTML, FO, PDF, whatever. - Stored content should be arranged in content blocks that are thoroughly tagged. Like all sections relating to kwm, should have a "kwm" tag. So if any major changes happen to kwm, all related content can be easily located and checked. - Vendors should be able to assemble custom manuals within a few clicks, if they don't opt to use pre-printed booklet thingies. - *Loads of style guide suggestions here* Ack! Aaaaaack! I totally hate you guys, really I do. :) Ok... I'll post something small at thetuxproject.com soon and see if anyone bites. |
| Sander_Marechal Feb 03, 2009 2:18 PM EDT |
jacog: Do some reading on DocBook XML. That should be perfect for the job. It does all the tagging that you want. Can be outputted to all the formats that you want and you can build it modular, i.e. every section in a separate file and then simply "include" the sections that you want in a single document. |
| jacog Feb 03, 2009 2:40 PM EDT |
Awesome. |
| land0 Feb 03, 2009 7:23 PM EDT |
@Sander_Marechal Good call! @jacog http://thetuxproject.com utilizes http://Drupal.org so the wiki books are able to export to docbook format. I will setup the wiki book as soon as you post it. We can then hammer out the workflow for exporting. So I will commit to getting all of the tools in place for you. I will also commit to post on the various web-book forums about the project. As I have time. Any thoughts? |
| Scott_Ruecker Feb 03, 2009 7:30 PM EDT |
Looks like jacog's big mouth got him some working to do...;-) |
| Sander_Marechal Feb 03, 2009 9:08 PM EDT |
land0: Unless you can edit pages on your website directly docbook format, I would not recommend that. DocBook has much more semantics than wikitext has. In order to get the modularization and tagging that jacog wants then you really need to write directly into DocBook (either using a text editor or a specialized DocBook editor) and not in some other format. You will loose too much semantics. |
| jacog Feb 04, 2009 4:54 AM EDT |
Hmmm, a tough call. I had a look at Docbook, and I am very happy with it as a format since I am comfortable with XSL and thestufflooselyreferredtoasxml. I think, I think, I think... I will build a custom site for editing the stuff that has the basic functionality in place. And then I will also post today on The Tux Project to get some brainstorming going, and perhaps find the odd volunteer here and there to beat my ugly code into shape. ;) I can only get to the real heavy lifting about three weeks from now, since I am about to undergo some terrifying, exciting, insane life changes next week. But definitely will try and get discussion going and at least shape the vision and convey it in such a way that everyone will understand the the motivation and purpose of it. And I will reiterate this on the other site, but it's important to remember: This is above all a marketing effort designed to smooth a new person's entry into the world of whatispopularlyreferredtoaslinux, not a technical documentation one. And certainly not intended to replace books. I worked for 5 years at the new media division of a large advertising agency... and from experience, marketing + geekery can be like oil and water. Licensing will be an interesting thing to decide on too. Anyway... off to some meetings. Yay. |
| Sander_Marechal Feb 04, 2009 5:33 AM EDT |
@jacog: Also look into entety references in DocBook. That would be ideal to quickly brand the documentation. Sprinkle the docs with references to &distro; &laptopbrand; &manufacturer; &logo; etcetera. All you'd need to do to assemble the book is a 20-line DocBook file that defines these entities and includes the parts that you need. Voila, instant branded user guide :-) |
| ColonelPanik Feb 04, 2009 12:00 PM EDT |
Where are my booklets? |
| jacog Feb 04, 2009 1:53 PM EDT |
I believe they are cutting down trees somewhere as we speak. |
| land0 Feb 04, 2009 2:16 PM EDT |
@ Sander_Marechal The plugin that is available for Drupal converts from HTML to DocBook format. Interestingly the creator of the module based his conversion on the standards made available directly from the DocBook project. So all things considered exporting to the DocBook format via Drupal should be fairly clean. IMO a web based editor that is easy to use and has the ability to create or export clean DocBook markup is the way to go in context of collecting contributed documentation and screen shots. The added benefit would be a very low learning curve which could serve to maximize the inclusion of people of all differing levels of geekdom. :) I suppose the contributed documentation could then be imported into the more geeky master document or... ? Anyway this has given me an excuse to learn more about DocBook. Good stuff all the way round really. |
| Sander_Marechal Feb 04, 2009 9:43 PM EDT |
land0: Of course it's clean, but it's also basic. You get things like "this is a paragraph", "this is emphasised", "this is a link", "this is an image". etcetera. What you don't get is the real semantic benefits of DocBook like "this is the application name", "this is a menu item, which is in a submenu of that menu item", "this is a warning/note", "this is console output", "this is a screenshot" (as opposed to a generic image), etcetera. Also, you won't get the modular setup (I presume that the Drupal plugin exports full books or articles, not parts that you can assemble later on) and you won't get the nifty entity reference stuff I talked about above to provide for quick branding. You need a drupal module that works the other way around. Write in DocBook XML and have the result automatically converted to HTML for display on your website. |
| jacog Feb 05, 2009 5:44 AM EDT |
Well, thar she blows: http://thetuxproject.com/?q=node/320 I have included a note stating that methinks the content should be treated like any other kind of source code - managed using CVS/SVN. |
| ColonelPanik Feb 05, 2009 12:00 PM EDT |
Jaco, That is sweet! Could we start with a double sided card, 8½ X 6½ inches or ½ of a sheet of US Letter or ½ sheet A4. The card would be generic Linux need to know to make it work. The card would ship with every Linux box regardless of Distro. Maybe I should put this idea on The Tux Project site? http://thetuxproject.com/?q=node/320 |
| hkwint Feb 05, 2009 6:24 PM EDT |
That's the sad thing about making some documentation: You always have to learn some documentation 'platform', which absorbs so much effort that you almost forget about the documentation you were going to write. I had the idea of making some doc-animations, but I still have to learn Synfig. |
| gus3 Feb 05, 2009 7:06 PM EDT |
Will you get those animations onto the printed page? *That* would be a neat trick... |
| Sander_Marechal Feb 05, 2009 7:23 PM EDT |
@Hans: DocBook isn't just *some* documentation platform. It's very, very widely used. If you like to contribute to documentation then you would do well to learn DocBook alongside HTML and manpage format. |
Posting in this forum is limited to members of the group: [ForumMods, SITEADMINS, MEMBERS.]
Becoming a member of LXer is easy and free. Join Us!