Den 19. april 2012 03:11, skrev Jeremy Bicha: > Your topic mixes developer docs, entry-level user docs, and "power > user" docs. Each of those needs a different approach and I think it's > simpler to tackle them as three mostly separate things. Also, if > you're going to discuss documentation, you should probably include the > docs team (CC'd now) as that's where people interested in that read.
The point is the exact opposite. We shouldn't split documentation up into completely unrelated pieces. That is the problem. We should consider it a whole. One single tree of knowledge. Before a release, we should be able to walk the entire tree and make sure all documents are Obviously Valid. You don't have to specialize in a single topic in order to do that. It just requires effort, and for that, it must be obvious what to do. With different docs being at different places, organized in different ways, maintained by "unrelated" teams and mixing versions, it's very difficult to do any kind of quality assurance or to do anything in a systematic way – as a whole. But for documentation to be seen as a whole, related software must sometimes also be seen as connected. That's why I replied here, since Unity is my main example. It's not simply about documentation. For instance, if I want to learn how to write a Python application for Unity, I have to read this: Unity-5.0 AppIndicator3-0.1 Indicate-0.7 ... They are obviously connected, but it's not at all obvious in versioning or documentation. I'd like to see something more like Unity Specification 1.0 Documentation, which would include those technologies. I'd like to see a Vala/GTK implementation of the Dash, for instance. And it'll have completely different versions than those listed above. This means that we can't just adapt documentation to software, but also adapt software to be more documentable in a way. I don't think this has to be very difficult, but it requires discussions and decisions. Seeing the bigger picture. The desktop is the most visible, most important aspect in this regard. Jo-Erlend Schinstad -- ubuntu-desktop mailing list [email protected] https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
