?

Log in

No account? Create an account

Wikibooks, Open Source Books

« previous entry | next entry »
Jun. 24th, 2008 | 09:17 am

One of the projects I am working on right now needs a manual, not just man pages, but an actual manual.

My goals:

  • Online All documentation should be online and editable online. Anyone should be able to edit it. Anyone should be able to extend it. We live in a Wiki world, and the day and age of collaborating via controlled copies is over. (And yes, this is something I very much dislike about the MySQL Manual)

  • Hosted Find a hosted solution that I do not have to maintain. Maintaining software takes valuable time from me. I only keep hosting mailing lists but Google Apps lacks this feature. For a Wiki? Someone else can do it. The solution needs to be non-onerous though.

  • Exportable. Sometimes you want a book in your hands, and for this reason I think books in the "it is a dead tree Jim" are good things. Skip a few years into the future and it is probably going to be an electronic book. People still want to have the book in their hands. In a perfect world they will want to have it in their hands, be able to change it in their hands, and then synchronize the transfer of their corrections back to the main book.

  • Information Should be Free No one should have to pay to access it, and just as importantly I want to make sure that anyone is free to take the book from the website and print it. If an outside publisher can print a thousand copies and sell it, I think that it is awesome. No onerous sign up processes. Anonymous is quite fine.

    So what do you think? Wikibooks? Is there another solution out there?
  • Link | Leave a comment | Share

    Comments {17}

    Artur Bergman

    (no subject)

    from: crucially
    date: Jun. 24th, 2008 04:30 pm (UTC)
    Link

    Wikia would happily host this.

    You might want to explore setting up under a CC license and not GFDL, but we can accommodate both. We are hosted, we know wikis, we have good spam tools. You can download the database dumps that we generate every night. (And soon a XMPP stream of all changes.)

    The offline synchronization problem is something i want to do, but mediawiki technology isn't there yet.

    Reply | Thread

    Choices available

    from: atcurtis
    date: Jun. 24th, 2008 06:03 pm (UTC)
    Link

    A quick google found this http://doc-book.sourceforge.net/homepage/
    Looks interesting - an online book collaboration which can display as HTML as well as dead-tree formats such as PDF and more.

    Reply | Thread

    TikiWiki CMS/Groupware

    from: marclaporte
    date: Jun. 24th, 2008 07:28 pm (UTC)
    Link

    Hello Brian,

    I think many Wiki engines may correspond to your general description. I will describe the one I use (TikiWiki CMS/Groupware) and why I think it's great for collaborative documentation and to foster a community.

    TikiWiki CMS/Groupware is a full-featured, tightly integrated, open source, multilingual Wiki-CMS-Groupware, written in PHP and actively developed by a large international community. Over 170 have contributed to the source code, and several times more to the documentation, support, bug reporting, etc.

    1- Used to manage the multilingual support site (wiki + forums) for Firefox:
    http://support.mozilla.com/

    2- We eat our own dogfood and when exported to PDF format, it weighs in at 962 (!) pages.
    http://doc.tikiwiki.org/files/Tiki19beta.pdf

    3- After years of challenges of trying to keep our multilingual documentation in sync, we now have a very sweet tool to handle synchronization of content in a wiki context (source document always in flux, no master version, etc):
    http://wiki-translation.com/CLWE+Demo+Screencast

    4- Structures to make it book-like and have a table of content:
    http://doc.tikiwiki.org/Structures

    5- Comments below the wiki pages
    Even if people can edit pages, in some cases, they will prefer to comment below
    http://doc.tikiwiki.org/Comments

    6- Staging and Approval
    I understand you want to keep it open. But if one day, you want to have more control:
    http://doc.tikiwiki.org/Wiki+Page+Staging+and+Approval

    7- Page ratings
    Ex.: "Was this page useful?"
    http://doc.tikiwiki.org/Rating

    8- Alternate content per version
    If you are documenting software, you will run into the situation where most of a page is similar for two versions, but there could be a small difference.
    http://doc.tikiwiki.org/PluginVersions

    9- Tags & Categories
    For easier finding of related stuff
    http://doc.tikiwiki.org/Tags
    http://doc.tikiwiki.org/Category

    10- Watch a page or a category (email notification of changes)
    http://doc.tikiwiki.org/Watch

    11- Hundreds of built-in features
    It has more features than you could ever need. You can start with the wiki and feel confident that if you need features down the road (ex.: bug tracker, blog, newsletter, etc), they are built-in. No need to install separate apps. In TikiWiki, you'll have a unified user/group & permission system. The look & feel, navigation, search, etc. will be consistent.
    http://doc.tikiwiki.org/Features

    12- Open Source, community project and easy to host.
    TikiWiki is a community project, licensed LGPL and runs on standard PHP/MySQL.

    13- Large community & actively developed
    http://tikiwiki.org/Top-10+stats


    I like to think of TikiWiki as the "Wiki Way" applied to software development. Here are my arguments to support this:
    http://www.marclaporte.com/TikiSucks


    As for a hosted solution, I am working on one. It's "invitation-only" at the moment, but you are invited :-) TikiWiki is 5 years old and nice and stable. But the WikiFarm stuff is still in development.
    http://ourwiki.net/


    What do you think?

    Best regards,

    Marc Laporte
    http://marclaporte.com
    http://tikiwiki.org/UserPageMarcLaporte

    Reply | Thread

    DVCS/ikiwiki?

    from: dmarti
    date: Jun. 24th, 2008 07:41 pm (UTC)
    Link

    If the project is under distributed revision control, you could make the manual an ikiwiki /manual directory inside the project, and periodically pull from one or more web copies. Might help keep the code and the documentation in sync.

    Reply | Thread

    Egor Egorov

    (no subject)

    from: egorfine
    date: Jun. 24th, 2008 08:39 pm (UTC)
    Link

    "Information Should be Free"

    Hmm... well I'm personally an old convinced open source evangelist, but I'm not yet sure about information. See, if I spent hundreds of man-hours to invent something which is purely an information (let's say I invented a new turkey recipe), I can surely give this info away for free, but why not sell it if there are people willing to buy it? :) Can you tell me, I really want to understand the "pros" of "information should be free".


    Reply | Thread

    Brian "Krow" Aker

    (no subject)

    from: krow
    date: Jun. 24th, 2008 08:54 pm (UTC)
    Link

    Let me put this in context. I have made very little off books, and computer books in general are not that profitable. To make a living off of them you will need to publish a lot of them each year.

    So for me making money is about people using my software. If the documentation draws more people in that is awesome. User base matters to me, not a few pennies from a book.

    Is this true for all contexts? No, but I do find that we humans do not get "intellectual property" at all. I am ok with this, because I believe there a good reason we reject it (aka we want to keep evolving).

    I should have probably have said "wants" instead of "should" but I find with my work it really does benefit me to keep it freely available.

    Reply | Parent | Thread

    Egor Egorov

    (no subject)

    from: egorfine
    date: Jun. 24th, 2008 09:05 pm (UTC)
    Link

    Aha, so the context here changes everything. Got this :)

    You know, I've seen people promoting "openness" as a dogma (we are not going to point our fingers at Stallman, don't we?), and didn't quite understood what this all means:)

    I believe people do not accept intellectual property simply because of their sensor feelings. When you own a thing, a real thing, and someone steals that thing from you - you don't have it anymore. Not the same for IP - if someone stole it, you ... still have it. You see, ownership of IP is unnatural! This is why it's hard, psychologically, to accept it. Do you agree?

    Reply | Parent | Thread

    Brian "Krow" Aker

    (no subject)

    from: krow
    date: Jun. 24th, 2008 09:23 pm (UTC)
    Link

    Yep, I agree with you that it is based on wanting our little monkey fingers to grasp it.

    I hum a song? Who is to blame for me lifting the copyright when I reproduce it? (or butcher it!).

    What do I keep as an open debate? Whether or not I care about commercial only modules linking to my stuff. As long as the API is open I really do not find that I care all that much. If the API is open, I can always implement my own if I care. Where I personally do not care to write closed modules, I do not really care if others do or not.

    Reply | Parent | Thread

    awfief

    (no subject)

    from: awfief
    date: Jun. 24th, 2008 08:56 pm (UTC)
    Link

    That's the difference between "should" and "must".

    We all "should" have clean water too.

    The only reason you want to sell it is because you need money to buy things, everything from the basics like food and shelter on upwards to things that make you think "hey, I'm pretty smart, I invented something useful and I have the BMW to prove it!"

    I agree with Brian's opinion that information should be free. It stems from my belief that so much growth has come from using information from previous work, "standing on the shoulders of giants" if you will. If every generation had to re-invent oral speech, then written speech, basic tools, on up to computing systems, we'd never make any "progress".

    There is a certain luxury in being able to give away what you spent hundreds of hours on; and this is a luxury I have been giving away ever since I was a poor college student, going to a soup kitchen for food when I didn't have enough for groceries (lest you think it's only the independently wealthy that have that luxury).

    That being said, there's nothing wrong with trying to sell a product you invested time in. Most of what I do, I do not mind giving it away for free, particularly if it would not be done otherwise.

    Reply | Parent | Thread

    Egor Egorov

    (no subject)

    from: egorfine
    date: Jun. 24th, 2008 09:10 pm (UTC)
    Link

    But when you think about society that doesn't require money to buy things, then you'll end up with... communism. Not a bad idea, btw, but totally impractical.

    You see, I understand that point of view. I myself do give away information for free, spending hours and hours creating it, I don't mind.

    But I cannot believe that market supports it. Say, I need a consulting - I go and buy it. And this consulting (information) exists exactly and only because there are people that are willing to pay for it. If this information will turn free, then it won't exist at all. To a certain degree, of course, it's not a one-bit world:)

    Reply | Parent | Thread

    Brian "Krow" Aker

    (no subject)

    from: krow
    date: Jun. 24th, 2008 09:29 pm (UTC)
    Link

    With consulting you are paying for someone's time :)

    You are paying to not do/learn something yourself. I can change my own oil, but I just pay someone to do it now a days (this was not always true).

    Communism? I find it about as impractical as pure capitalism. Open source I believe has far more to do with capitalism then communism. Open source is about bringing down costs, and offering up alternative models. We make billions into millions and take a piece for ourselves.

    No market protection :)

    Reply | Parent | Thread

    Egor Egorov

    (no subject)

    from: egorfine
    date: Jun. 24th, 2008 09:51 pm (UTC)
    Link

    "Open source I believe has far more to do with capitalism then communism."

    Ha! Didn't thought of it like that:) Nice point :)


    Reply | Parent | Thread

    Arjen Lentz

    it doesn't quite work that way...

    from: arjen_lentz
    date: Jun. 24th, 2008 11:21 pm (UTC)
    Link

    What you describe is not communism. But that's deviating rather too far from this thread.

    If you have expertise in a certain topic, writing openly about it and giving lots of info away does not hurt. In fact, it can help you in terms of marketing, recognition of your expertise, good karma, and so on. So you will be able to sell consulting and training effectively.
    Bits of good advice, or even a whole reference manual, are not the same as years of experience.

    Reply | Parent | Thread

    Egor Egorov

    Re: it doesn't quite work that way...

    from: egorfine
    date: Jun. 24th, 2008 11:34 pm (UTC)
    Link

    True, this is the marketing lesson the whole world learned from MySQL :)

    Reply | Parent | Thread

    awfief

    (no subject)

    from: awfief
    date: Jun. 24th, 2008 08:50 pm (UTC)
    Link

    I only keep hosting mailing lists but Google Apps lacks this feature.

    Um.....Google Groups? I think some words were eaten, and that takes your meaning away.

    http://www.rev2.org/2008/02/28/google-sites-hosted-wikis-for-group-sites/

    Seems like Google Aps has "jot spot" -- probably not what you want, but interesting.

    Adobe has Buzzword at www.acrobat.com which has the interesting feature of being able to comment/annotate, but it's more for a few authors and a few readers, not a few authors/multiple readers.

    http://en.wikipedia.org/wiki/Wiki_farm might be useful.....

    Reply | Thread

    Kytty

    (no subject)

    from: kytty
    date: Jun. 25th, 2008 03:59 am (UTC)
    Link

    Electronic books...the means to carry a traditional book with you is as close as the nearest library...electronic books take hardware that is prohibitively expensive. On the other hand, I like that font size can be changed in electronic books and would like to see them come with an application to feed a single line of large print text for reading.

    Sort of like this but with adjustable speed...

    Reply | Thread

    Brian "Krow" Aker

    (no subject)

    from: krow
    date: Jun. 25th, 2008 04:56 am (UTC)
    Link

    I think we will be down to cheap e-book readers within the next decade, so I am not overly concerned about that. You could condense a lot of text books into one e-reader and that to me would be pretty sharp for school systems.

    Now, what I am after though would allow others to print books, which I think is good. AKA I want the information to flow. If this means someone in China makes a buck on a book I am fine with that.

    Reply | Parent | Thread