Re: {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation
Maybe an every increasingly obvious banner at the top of every wiki page. This wiki was last edited 12/12/2012 - Green This wiki was last edited 12/12/2011 - Yellow This wiki was last edited 12/12/2010 - Red This wiki was last edited in 2009/8/7/6 and may not be accurate - Dark gray - David On 2012-04-24 22:17, Chris Wilson wrote: Perhaps some mechanism to archive obsolete yet relevant wiki pages would be useful here. I'm not sure if the current wiki engine has such a feature, or what sort of effort would be required to hack one in if it doesn't, but being able to classify wiki pages into separate tiers of importance could be helpful. I also think that keeping the docs for average users, power users, contributors and developers (there seems to me to be four sets of users, not three as has been mentioned earlier) makes sense since all of those groups have different needs. I as a developer would like to know how to navigate the Unity source code, or how to quickly learn the process for submitting a patch (from start to finish), without having to wade through pages of configuration file tweaks aimed at power users. A single landing page for everyone starting out may be appropriate, but after that I think they should diverge. Chris On 19 April 2012 08:30, Matthew East m...@ubuntu.com wrote: In my previous email on this thread, I dug out a specification created in 2005, for example. It was implemented over 5 years ago, and hasn't been touched since then, but keeping it around reminds us why we did something and can be used as a reference if a similar discussion crops up in the future -- ubuntu-desktop mailing list ubuntu-desktop@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
Re: {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation
Perhaps some mechanism to archive obsolete yet relevant wiki pages would be useful here. I'm not sure if the current wiki engine has such a feature, or what sort of effort would be required to hack one in if it doesn't, but being able to classify wiki pages into separate tiers of importance could be helpful. I also think that keeping the docs for average users, power users, contributors and developers (there seems to me to be four sets of users, not three as has been mentioned earlier) makes sense since all of those groups have different needs. I as a developer would like to know how to navigate the Unity source code, or how to quickly learn the process for submitting a patch (from start to finish), without having to wade through pages of configuration file tweaks aimed at power users. A single landing page for everyone starting out may be appropriate, but after that I think they should diverge. Chris On 19 April 2012 08:30, Matthew East m...@ubuntu.com wrote: In my previous email on this thread, I dug out a specification created in 2005, for example. It was implemented over 5 years ago, and hasn't been touched since then, but keeping it around reminds us why we did something and can be used as a reference if a similar discussion crops up in the future -- ubuntu-desktop mailing list ubuntu-desktop@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
Re: {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation
Absolutely. Indeed it should. Not only for different types of users, but for different trails as well. Again I use Unity as example. Suppose you want to start developing. You've covered the basics of the language, and now you want make something you can show your friends. So you do to the docs page developing Python Desktop Unity. There you find the Unity Specification 1.0 Documentation, with Indicators, Launcher, and everything. You learn how to make lenses and scopes, and there's lots of them to make in your area, so you just keep going and become really good at it. Then you begin to wonder how it works under the scene. So you go to the next level, which is the DBus architecture. You're still on the same trail, mind you. So you lean how the DBus bindings work in Python and then you move on to the DBus Unity API itself. That's the exact same document you'd end up with if you'd started with Vala, because after all, it's the same thing. If you've followed the Python trail already, you'll just get the Oh, I know this! feeling, which isn't a bad thing. So the main documentation tree might be grouped in libraries and then under language, as is the case on dev-u-c now, but to the user, it'll be presented by their interests, as trails. The documentation isn't just something that comes with the tools. The documentation itself is its own product with its own goals. Here's an example for you; I recently switched to BtrFS in Precise. I needed to learn, and I ended up here: https://help.ubuntu.com/community/btrfs. As far as I can tell, there's nothing particularly wrong with that information. But then, this stuff is new to me, so how would I know? It doesn't inspire confidence. Ubuntu-specific subvolume layout in 11.04 and later? I'm using 12.04! But I'm very familiar with this, so I scrolled down towards the bottom of the page to see when it was last updated. Just a few days ago. Nice. And I can see the page history. On my way there I noticed that most of the information is for 8.10! This is a filesystem we're talking about. I really need to be confident about this information, and the mere mention of 8.10 makes me suspicious. This page was marked out of date nearly four years ago: https://wiki.ubuntu.com/UbuntuOnMac. Why does it even exist? I assume it's simply because noone has the overview to systematically make sure pages like that is either updated or deleted. If noone has an overview, then it's difficult to attract contributors as well. Specific tasks makes it much easier. And by update, I don't mean adding new info on top, leaving older info below. One page per version. Reviewed. Obviously Valid. Facts aren't good enough anymore. We need to design documentation for the user. And that can't just be about deleting old wiki pages. We need a goal. A new way of thinking about documentation as a whole. Jo-Erlend Schinstad -- ubuntu-desktop mailing list ubuntu-desktop@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
Re: {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation
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
{Desktop 12.10 Topic] Holistic approach to Ubuntu documentation
I think it's necessary for Ubuntu to take documentation to another level. When I first started with Ubuntu, I really wanted to learn how it all fit together. I have used computers most of my life so I'm accustomed to reading documentation and I was perfectly willing to dive right in. But it just wasn't that easy, not necessarily because of the information itself, but because of how it was organized and presented. There were no clear starting point and no trails to follow. There were broken links on wikis, and outdated information lying around. Much of the documentation would only use version numbers, and have no easy way to see when it was last updated, or if it had been superseeded. Confusion reduces peoples ability to learn. To me, this is The Issue with Ubuntu. If we're really going to succeed in taking Ubuntu «across the chasm», then we must make it easy for the curious to become users and for the enthusiasts to become power-users. For this to happen, we need to do something drastic about the way documentation is presented. I think Ubuntu Documentation must: * Have an obvious starting point * Lead to the next step * Be instantly recognizable as valid or invalid * Be grouped when applicable * Primarily focused on LTS * Reviewed for each release (hence the point above) * Easy to contribute to by reporting issues * Be not only API docs, but contain readable text. developer.u-c and help.u-c has improved a lot in this regard, but not enough. Look at this page first: http://developer.ubuntu.com/resources/platform/api/12-04/. As a reader, I can come across issues that I'm not able to read, but will help improve the documentation. I should have a very easy way to report it. There's no way at all on that site, though at the very bottom, I can submit a tutorial. Another example, look at this page: http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html. Right, but that's Ubuntu 5.0. I was looking for 5.10. Is this still valid? There's no way to know. We shouldn't rely on people to trust that if not stated otherwise, it is valid. This is the web. There are millions of old and unmaintained documents out there. It must be obvious that it is valid. This also helps anyone recognize invalid documentation, enabling them to report it or fix it. And what if my primary focus is developing an application for LXDE and I want to use only an indicator? In this specific case, I'd use a separate version for the API docs and call it Unity Specification 1.0 for 12.04. Then if there are any changes between now and 14.04, I'd call that 2.0. For versions in between I'd add 1, 2 or 3. So, if there are API changes i 13.04, I'd expect to find a Unity Specification 1.2 and that it would clearly show the differences between 1.2 and 1.0, considering the newest LTS the In the case of Unity-5.0 for Python above, I'm not sure I'd call that Documentation. That is the convention, but I'm not sure that's what people expects. I'd call that document a Specification. For Documentation, I would expect more readable text, explaining what it's for and how it is used. Enum: Unity.FilterRenderer CHECK_OPTIONS_COMPACT 4 Right. How do I use it? .) Jo-Erlend Schinstad -- ubuntu-desktop mailing list ubuntu-desktop@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
Re: {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation
On 18 April 2012 20:39, Jo-Erlend Schinstad joerlend.schins...@ubuntu.com wrote: I think it's necessary for Ubuntu to take documentation to another level. When I first started with Ubuntu, I really wanted to learn how it all fit together. I have used computers most of my life so I'm accustomed to reading documentation and I was perfectly willing to dive right in. But it just wasn't that easy, not necessarily because of the information itself, but because of how it was organized and presented. There were no clear starting point and no trails to follow. There were broken links on wikis, and outdated information lying around. Much of the documentation would only use version numbers, and have no easy way to see when it was last updated, or if it had been superseeded. Confusion reduces peoples ability to learn. To me, this is The Issue with Ubuntu. If we're really going to succeed in taking Ubuntu «across the chasm», then we must make it easy for the curious to become users and for the enthusiasts to become power-users. For this to happen, we need to do something drastic about the way documentation is presented. I think Ubuntu Documentation must: * Have an obvious starting point * Lead to the next step * Be instantly recognizable as valid or invalid * Be grouped when applicable * Primarily focused on LTS * Reviewed for each release (hence the point above) * Easy to contribute to by reporting issues * Be not only API docs, but contain readable text. developer.u-c and help.u-c has improved a lot in this regard, but not enough. Look at this page first: http://developer.ubuntu.com/resources/platform/api/12-04/. As a reader, I can come across issues that I'm not able to read, but will help improve the documentation. I should have a very easy way to report it. There's no way at all on that site, though at the very bottom, I can submit a tutorial. Another example, look at this page: http://developer.ubuntu.com/api/ubuntu-12.04/python/Unity-5.0.html. Right, but that's Ubuntu 5.0. I was looking for 5.10. Is this still valid? There's no way to know. We shouldn't rely on people to trust that if not stated otherwise, it is valid. This is the web. There are millions of old and unmaintained documents out there. It must be obvious that it is valid. This also helps anyone recognize invalid documentation, enabling them to report it or fix it. And what if my primary focus is developing an application for LXDE and I want to use only an indicator? In this specific case, I'd use a separate version for the API docs and call it Unity Specification 1.0 for 12.04. Then if there are any changes between now and 14.04, I'd call that 2.0. For versions in between I'd add 1, 2 or 3. So, if there are API changes i 13.04, I'd expect to find a Unity Specification 1.2 and that it would clearly show the differences between 1.2 and 1.0, considering the newest LTS the In the case of Unity-5.0 for Python above, I'm not sure I'd call that Documentation. That is the convention, but I'm not sure that's what people expects. I'd call that document a Specification. For Documentation, I would expect more readable text, explaining what it's for and how it is used. Enum: Unity.FilterRenderer CHECK_OPTIONS_COMPACT 4 Right. How do I use it? .) Jo-Erlend Schinstad 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. Thanks, Jeremy Bicha -- ubuntu-desktop mailing list ubuntu-desktop@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
Re: {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation
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 ubuntu-desktop@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
Re: {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation
On Thu, Apr 19, 2012 at 03:51:02AM +0200, Jo-Erlend Schinstad 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. 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. Well, both of you make valid points. Can the documentation be *maintained* in a single tree, yet split out by user type (one set for my mom, one for me)? Bryce -- ubuntu-desktop mailing list ubuntu-desktop@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
