FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Ubuntu > Ubuntu Desktop

 
 
LinkBack Thread Tools
 
Old 04-19-2012, 12:39 AM
Jo-Erlend Schinstad
 
Default {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
 
Old 04-19-2012, 01:11 AM
Jeremy Bicha
 
Default {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation

On 18 April 2012 20:39, Jo-Erlend Schinstad
<joerlend.schinstad@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
 
Old 04-19-2012, 01:51 AM
Jo-Erlend Schinstad
 
Default {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
 
Old 04-19-2012, 03:51 AM
Bryce Harrington
 
Default {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
 
Old 04-19-2012, 06:19 AM
Jo-Erlend Schinstad
 
Default {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
 
Old 04-19-2012, 07:23 AM
Matthew East
 
Default {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation

On 19 April 2012 02:51, Jo-Erlend Schinstad
<joerlend.schinstad@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
 
Old 04-19-2012, 07:30 AM
Matthew East
 
Default {Desktop 12.10 Topic] Holistic approach to Ubuntu documentation

On 19 April 2012 07:19, Jo-Erlend Schinstad
<joerlend.schinstad@ubuntu.com> wrote:
> 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.

It seems to me that there is a good reason to take a different
approach to user help than to contributor documentation as regards
deletion of material.

There are quite a lot of pages on wiki.ubuntu.com that are out of date
but that have specifically not been deleted because they can have
historical value. So, looking back over the development of Ubuntu
historically can sometimes be useful, to remember why something
happened in a particular way. 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. (I'm not
saying this necessarily applies to the page you've referenced above,
the explanation may be a less sophisticated one, like no one has had
the chance to merge the information into whatever database is now used
for such things, or simply that it should be deleted but hasn't yet
been.)

That's not the case for user help, there is no point keeping around a
page which can only be applied to a deprecated version of Ubuntu on
help.ubuntu.com. So evaluating the issue of deleting information using
a single process isn't helpful.

--
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
 
Old 04-24-2012, 12:47 PM
Chris Wilson
 
Default {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 <mdke@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
 
Old 05-25-2012, 05:50 AM
David
 
Default {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 <mdke@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
 

Thread Tools




All times are GMT. The time now is 03:44 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright ©2007 - 2008, www.linux-archive.org