On 19 April 2012 02:51, Jo-Erlend Schinstad <joerlend.schins...@ubuntu.com> wrote: > 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.
I don't agree with this, and I agree with Jeremy. The fact that information provided to help users (help.ubuntu.com), information provided to help application developers (developer.ubuntu.com) and information provided to help contributors (wiki.ubuntu.com) could all be given the single label "documentation" or indeed "information" is just a matter of language. The three concepts are so fundamentally different that they justify and require a completely different approach, different websites and even a different authorship. It's not useful to think of them as different aspects of the same thing. They aren't. This is particularly important for users. We mustn't burden users looking for help with Ubuntu with the sort of complex and confusing information that is found on wiki.ubuntu.com or developer.ubuntu.com. We worked quite hard back in 2006 to separate these concepts out (https://wiki.ubuntu.com/BetterWikiDocs) and I think it's important that we stand by it. Furthermore, the type of information being presented to users is so different to that presented to developers that it warrants different structure and a different style. As to authorship, developer material is usually best written by developers, because they know what they are talking about and have been through the process of learning about those concepts, whereas it's less common (albeit not impossible) that developers make good authors of user help because there the level of knowledge required is different, and the focus is on the skill of explaining something to a non-technical user in the most effective way. So good writers of user help are often non-technical people themselves. Having said that, I think that you also make a perfectly valid, point about the validity, quality and process used to updating documentation. Nothing I have said above is intended to suggest that we have a good process for user documentation - there is vast scope for improvement almost at every level, both in the structure of the user documentation, the quality of it, the number of contributors attracted, and so on. However, these types of points are entirely separate from the main point which you make about eliding different types of documentation. In relation to quality and process, you give a few specific examples of pages which are out of date and which are difficult to rely upon. I've no doubt you could have given dozens of examples. On the help wiki, we do have a way which has been established of dealing with such pages: https://help.ubuntu.com/community/Tag For example, you mentioned this page: https://help.ubuntu.com/community/btrfs You're right that it seems to be drafted for older versions of Ubuntu, so I've added the "unsupported" tag. Your point of course would be that when you visited that page, in the role of a user, you weren't to know that the page could be out of date. And you're right that it would be useful to discuss whether there could be some kind of systematic process whereby pages are reviewed and updated on a regular basis, or whereby users themselves can report problem pages more easily than they can now. Any such discussion has of course to take into account the fact that there are actually not a lot of contributors to documentation. It therefore needs to be coupled with a separate discussion about how to attract more contributors. Such a discussion would be very useful. There are plenty of new ideas and approaches we could consider with a view to improving the user documentation. -- Matthew East http://www.mdke.org gnupg pub 1024D/0E6B06FF -- ubuntu-desktop mailing list ubuntu-desktop@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop