Edward, You have suggested that we need to get the gstreamer tutorials out to more people. I agree. I already put a link to my the demos on the wiki, but I think the wiki itself would be the best place for them. Allowing other people to be able to make instantaneous corrections and updates is extremely valuable.
Before starting on the demos, there were thee main issues I identified as barriers to writing good documentation. I solved these problems in the simplest way I could think of: using familiar programming tools to pre-process HTML files. I would like to take some steps to address these problems on the wiki before moving the content over. 1. Including diagrams in articles. Vector graphics programs are, by far, the easiest way to do this. It would be awesome to have editable versions of the illustrations available on the wiki. I favor Dia for the kind of illustrations I have been producing because of Dia's concept of connection points. This makes rearranging diagrams composed of boxes and arrows really easy. Dia also has sane defaults for exporting to .png. By far the easiest way handle this issue would be with this wikimedia extension: http://www.mediawiki.org/wiki/Extension:Dia 2. Including Demonstration Programs in the article I have learned from experience that is a bad idea to insert example code into documentation manually. Usually what happens is that bugs are found and corrected in the example program, but not in the article itself. I think that synchronizing different copies creates a lot of unnecessary confusion. Running code should be maintained in a separate file, and #included into the article, ideally after being run through a syntax highlighter. Being able to do this has saved me a lot of manual editing: I write the demonstration code and the article in tandem, making frequent corrections to both, until the article is finished. I have found two wikimedia extensions which can handle this: http://www.mediawiki.org/wiki/Extension:C_Style_Wiki_Includes #include support http://www.mediawiki.org/wiki/Extension:ASHighlight syntax highlighting 3. Quoting Excerpts of Example Programs Nothing disrupts the flow of a piece of technical writing like a two-page source-code listing. To help alleviate this, I added the ability to quote excerpts of a demonstration program to my preprocessor script. This allows me to write articles in a more natural style while still maintaining the _working_ code in a separate (and executable) source file: <commentary> <code fragment 1> <commentary> <code fragment 2> .... I do this by inserting <excerpt Number> ... </excerpt> inside comments in the source file, which the preprocessor extracts with a regex. I did not find a ready-made wikimedia extension for this. However the #include code above isn't entirely different from the code I wrote to handle demonstration programs, so perhaps I could hack in support for excerpts. ------------------------------------------------------------------------- This SF.net email is sponsored by: Splunk Inc. Still grepping through log files to find problems? Stop. Now Search log events and configuration files using AJAX and a browser. Download your FREE copy of Splunk now >> http://get.splunk.com/ _______________________________________________ Pitivi-pitivi mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/pitivi-pitivi
