ubuntu-manual team mailing list archive

[Ilya Haykinson <haykinson@xxxxxxxxx>]

Alan,

First, thank you for reviewing the survey and responding.

I have explained to Benjamin that I'm uncomfortable with the amount of
> focus being placed on getting the manual onto CD/ISO. Especially given
> it's so far unfinished, and not in main so ineligible to get on the
> CD. Putting pressure on the project to put this unfinished manual on
> the CD on the proviso that it may be ready on time raises a few
> issues: ...
>

I understand your point of view. My goal in creating the survey was to start
with the existing questions as asked on the Ubuntu forums, and use feedback
from the list to come up with something more useful.

In general, I agree with you; I think we're putting the cart before the
horse -- _if_ we come up with a manual that's of the right level of
comprehensiveness, quality, usefulness, only then can we have a real
discussion about including it in the distribution. Otherwise to some degree
we're a bit like some group of software developers saying "we've got this
great idea for a new software package; we're only a few percent of the way
into the work, but can you guys commit to distributing it?". I don't think
anyone would go for this, and neither should they go for a manual that's not
finished.

So the correct course of action for us is to first come up with something
great, which we're definitely trying to do, and only then try to sell this
idea to others.

Separately, there is a bit of a truism in the question of whether the manual
should be included with Ubuntu -- it wouldn't make much sense to disagree
with the assertion that it should be included (who would want to place a
useful piece of information in a less convenient location, on purpose?).

This question will be removed.


> * In the event that the Ubuntu Manual team is unable to maintain the
> package (are there any MOTUs in the manual team?) it will likely fall
> to the Documentation Team to maintain the manual in the future. What
> provision has been made for this? Will the Doc team be happy
> maintaining two separate sets of documentation? (I suspect not)
>

While I don't think we have any MOTUs on the team, there is certainly a
potential that the manual will fail to be maintained. The only way we can
"guarantee" that to not be the case is to successfully go through at least a
couple of releases of the manual, I suppose.

However, you bring up a point that I've seen mentioned before -- about the
manual being just a separate set of documentation. I think that a good
manual is expressly not the same as standard documentation. Good docs are
task-based, and are primarily a reference -- one uses the docs to solve
specific problems, and get the maximum depth on a subject. A good manual, on
the other hand, presents a high-level narrative that can be followed from
beginning to end -- it is quite normal for people to read good manuals
cover-to-cover before starting to use something. In addition, a good manual
does not go into much depth: it does not exist to tell people how to do
everything, but rather to tell them what kinds of things are possible, and
get them started.

With these distinctions in mind, I think that there is actually not very
much overlap between the online help that the docs team has been great at
creating, and the intended end product of the manual team. While, again,
it's a question of the future on who will maintain it, I think that there is
more than enough room for a really good, open-content manual in the ubuntu
universe.


> "If it was to be included by default, do you think it should be on the
> desktop?"
>
> I think this question highlights a lack of knowledge of the "rules" of
> the desktop in Ubuntu. It's a pointless question because we do not put
> _any_ icons or links directly on the desktop in a default install. I
> would recommend you remove it. If it were to be on the CD then it
> would likely be placed in a shared folder
> "/usr/share/doc/ubuntu-manual/" for example, and a link placed in some
> other folder, but there wont be an icon on the desktop, end of story.
>

Wonderful criticism. Question will be removed -- this decision belongs to
other people in Ubuntu, not the manual team in any case.


>
> > Note that in the free version of the tool I can only ask 9 questions
> (plus
> > one slot that is used for the intro text), and can't have conditional
> logic
> > in the questions. I think that is not a serious limitation -- anything
> > longer is unlikely to get answered anyways.
> >
>
> Don't let the tool dictate the questions. If you want to ask more
> comprehensive questions then use another tool. Other survey systems
> are available, there's no rush to get this done in the next 7 hours.
>

I think I didn't phrase this correctly. Here's what I want to say:

 - please don't mail this link out yet; the survey is not final
 - if I don't hear any feedback, I will post this soon (i.e. tonight); if
there is feedback, let's hold off until there's consensus on the design
 - if you ask for certain changes, I may not be able to make them with the
tool that I'm using. I've looked at a few other tools that are more
flexible, and which we can certainly choose to use, but I think that the
limitations of the current tool are actually quite helpful in ensuring a
short, reasonably focused survey.

Hope this explains my point better.

-ilya