GNOME Bugzilla – Bug 756643
The order in which to read the documentation is not clear
Last modified: 2015-10-15 14:20:16 UTC
This page: http://gstreamer.freedesktop.org/documentation/ reads in the first row: Application Development Manual (Read this first) "Read this first" assumes it is a starting point for someone willing to learn GStreamer. And although parts 1 and 2 of the aforementioned Development Manual could really be read and understood by a newcomer, part 3, which is titled Advanced Concepts is way too hard for a "read this first" document. So my suggestion is either move Part 3 to a separate manual, or have a statement(s) in it saying "If you are learning, and reading this as your entry point into the GStreamer, skip this, this and this page/chapter." In fact, Chapter 19 even says "be assured that you'll need ...good understanding of GStreamer before you start reading this". Which contradicts the "Read this first" clause in the beginning. You either "read this first" or "have a good knowledge of GStreamer", right? I understand the intention was to add more and more detail to the manual, but it becomes too hard to read for an unprepared, and you do not know which parts can be skipped when you read it as your entry point into GStreamer world. And when you are unprepared where do you start?
Thanks for pointing this out, and I see where you're coming from, but it's not really clear to me what to do with this. Our documentation already consists of too many documents, splitting this out into yet another one doesn't make much sense to me. Seeing that this is under an 'Advanced GStreamer concepts' heading it's probably clear to most people that this is not the first thing to read. In my experience very few people read things from start to finish but will jump from section to section depending on what they need right there and then. I agree that our documentation requires a structural overhaul in its entirety though, and we also need to present different content to get started, but that's a different issue and this particular ticket is WONTFIX in my opinion.
Thanks. For me, if there was a hint at the beginning of Part-3 similar to "Please do not read beyond this point if you are just started learning", would really saved many hours.