Hi all, So right now we have two main sources of documentation to point people at:
* The ROG * The tryphon wiki There's some issues here: * The ROG is outdated and while often useful, sometimes misleading and hard to reference * The tryphon wiki is similar, with the added bonus of being full of useful use-case demonstrations and contributed documentation - but it's not very well organized or presented, and is hard to find things on. Documentation is really important for Rivendell to succeed and is one area we can, as a community, really help out on. We can't all write C/C++, and those of us who can often don't feel comfortable leaping into as large and complex a project as Rivendell. I'd like to propose a solution from the community. We all want good docs, and personally I'm happy spending some spare hours documenting Rivendell, even though I'm no longer involved at a station running it. I'm sure people who have stations running it would be up for helping to better document the system for the benefit of their station and others. We've got the manpower, we need some structure. So, my proposal is this: * We set up a new, blank, completely fresh wiki. This could be hosted by Paravel or hosted by the community - I'd be happy to host it if nobody else is. MediaWiki is a good tool for documentation, and is open to everyone (as long as there's some anti-spam measures in place). * We work out some good rules of thumb for presenting sorts of information, and set up templates for categorization and basic information. * We set up a structure, dividing the wiki into: ** Concepts, Design and Technical Information - What it is and how it works, the basics and the details. ** Installation - How to get Rivendell from "I have a computer running X" to "playing audio out 24/7 randomly picked from the library" as simply as possible ** Usage - Basic Rivendell usage, documentation on how to use features, what all the apps do. How to set up complex stuff like clocks, logs, music scheduling internally or with an external program, and so on. ** Examples - Use cases and examples of how to set up Rivendell to accomplish common tasks or pull off complex configurations We could split up the categories, especially under usage/examples, to expand further on topics like scheduling, log editing and generation, and library management. We should have good defined ways to present things like source code, shell scripts, and commands for users to run, and so on, for examples and extensions. I really think Rivendell could benefit a lot from improved documentation - good docs and manuals help sway people unsure of an open source product where commercial support is unavailable or hard to come by (the USA has Paravel, the EU has a few companies, but plenty of countries have no commercial support), and for some stations it isn't an option. More users means more feedback and a bigger community and that's a win for everyone. Does this sound like a plan? Is anyone else interested in helping write the best documentation for the best open source playout system? Am I missing anything huge? Am I mad? Cheers, James Harrison _______________________________________________ Rivendell-dev mailing list [email protected] http://lists.rivendellaudio.org/mailman/listinfo/rivendell-dev
