Skip to main content
Welcome guest. | Register | Login | Post

feel the fear and do it anyway

14 replies [Last post]
tbuitenh's picture
Offline
Joined: 2005-12-21

from here:

Kathy Sierra wrote:

Sometimes, with some products, it's OK to say, "We can't make this any easier or less scary, but we can help you come out the other side."

...

Quote:

helping a user be afraid and do it anyway is a powerful force. We shouldn't be too quick to over-simplify a product or experience. Of course, it's up to us to get our users through the big, challenging, thing--there's a big responsibility for stellar documentation and support. And we're talking moral support, not just tech support, so building a user community is even more important with something really, really, scary.

Does anyone else think "command line" and "man pages"?

An old idea of mine is that man pages could be made more helpful by making them interactive: tick or perhaps drag'n'drop some options described in the man page, fill in form elements attached to them, then execute the command you assembled that way.

And here's a new idea I had while talking in #libervis yesterday: improving man pages by adding in the community. Make it possible to add "sticky notes" to parts of a man page you don't understand, which others can then look at and give helpful comments on. I bet it could be implemented on nuxified.org using some kind of drupal module and a man to html converter. Does a drupal sticky notes module exist?

A similar idea, but perhaps harder to implement with only preexisting software: convert man pages to html, put them on nuxified, and give each option in each manpage a html anchor, so it becomes possible to give a link to the appropriate option in a manpage. Of course it could also be a side effect of the other idea: one could insert a sticky note in the place where one wants a user to look, then link to that.

What do you think?

a thing's picture
Offline
Joined: 2005-12-20
unnecessary

I don't think this is really necessary. If someone doesn't understand documentation, asking in the already-setup forums is fine. If it's actually a problem with the documentation, that should be a bug report.

tbuitenh's picture
Offline
Joined: 2005-12-21
There's a difference

There's a difference between helpful and necessary.

free-zombie's picture
Offline
Joined: 2006-03-08
it sounds kind of

it sounds kind of interesting, but, due to the lack of meta-data in man pages highlt diffilult

tbuitenh's picture
Offline
Joined: 2005-12-21
What do you think the

What do you think the meta-data is needed for?

free-zombie's picture
Offline
Joined: 2006-03-08
There is no way for a new

There is no way for a new man page reader to recognize a command or an argument to be significantly more useful than the man/forum conbination we have anyway.

Especially hyperlinks are something man pages could greatly benifit from - the concept is non-existant (other than in the INFO system for example)

tbuitenh's picture
Offline
Joined: 2005-12-21
We seem to be thinking of

We seem to be thinking of entirely different things. :/

libervisco's picture
Offline
Joined: 2006-05-04
Alright, I'm finally

Alright, I'm finally chiping in here. Smiling

You're thinking about HTMLizing man pages and then making it possible for users to add tags or stickies to each paragraph they don't understand and would like to see clarified, right?

I guess what free-zombie means, even though he may be thinking about something different, is that this might not be all that different from forum topics. One sticky would basically be like a question, and helpful comments given to it are replies (like in forums).

But then again I guess it could be beneficial if we could integrate tagging/stickying onto the content of man pages and opening new topics in forums, in this way:

When someone reads a web man page for ifconfig (for example) and then selects a paragraph they don't understand by posting a "sticky" on it, the content of the sticky would in fact be the content of a new forum topic being opened in the networking forum. As people add responses (just as they usually do on forums) the little sticky on that man page just updates a link saying something like "read more, 2 comments". "Read more" leads to the full version of the content of the sticky and "2 comments" to the comments to this sticky/topic.

Man pages could be similar to what GPLv3 comments page has, but with the popup on the right linking to the forum topic. Smiling

tbuitenh's picture
Offline
Joined: 2005-12-21
Yes, you got exactly what I

Yes, you got exactly what I meant.

libervisco's picture
Offline
Joined: 2006-05-04
Sounds like a cool thing.

Sounds like a cool thing. Well I can't make any promises. What I can do is download the source code behind that GPLv3 comments page and look into it. The wiki page from which I downloaded it says that it's "daunting to install" (that's all it says about it), so I expect it'll take a bit of time to figure out.

I'll look for if there are any modules that can do something similar, but I have my doubts about that. The toughest thing in the end will probably be integrating this thing with forums. However, even if the integration wouldn't be available at first, I think just having a section with man pages commentable the way GPLv3 license comments page is, will be quite good.

All this said, though, I am not sure how popular would this be in the end and how best to promote it. We have to find out whether there are enough people who think this is a good idea and who think this would really help them.

a thing's picture
Offline
Joined: 2005-12-20
You're right.

There is. I don't think it will be that helpful either though. How many people now are starting forum topics about manuals?

free-zombie's picture
Offline
Joined: 2006-03-08
subject field is required
libervisco wrote:

HTMLizing

that's where my point lies. HTML lives off hyperlinks, and they would be bloody useful in new man pages like that, BUT it's impossible to automatically extract such links from man pages as we have them today.

A new man reader, be it web-based or not, could benefit a lot from data not in man pages. New features may attract users who don't particularly care about the Q&A system. They might be asked "Do you want to participate...", a wee bit later see a question and thing "What ? This is obvious. What the heck, I'll just answer this."

tbuitenh's picture
Offline
Joined: 2005-12-21
None, but perhaps you

None, but perhaps you should ask: how many people now are reading manual pages, thinking "I don't get it, I'll use a different tool / do it manually"?

That said, I do think it would be better to have an offline manual reader that can optionally fetch notes written by others. It's indeed unlikely someone will read a manual offline, then look that same manual up online to ask a question about it. This has to be a matter of one or two clicks...

So perhaps we shouldn't make a half-***ed implementation here but keep the idea for a future software project.

tbuitenh's picture
Offline
Joined: 2005-12-21
IIRC man2html does

IIRC man2html does automatically create links in the "SEE ALSO" section.

a thing's picture
Offline
Joined: 2005-12-20
changing info

Perhaps modifying GNU info would work for that.

Comment viewing options