Archive of UserLand's first discussion group, started October 5, 1998.

Re: Sample code and utilities?

Author:Paul Howson
Posted:3/29/1999; 3:56:58 PM
Topic:Sample code and utilities?
Msg #:4672 (In response to 4634)
Prev/Next:4671 / 4673

Hmmm. Some of the comments so far are a bit too nitty gritty technical for my liking.

I find that the most serious shortcoming in contributed Frontier software is the standard of documentation. At every level, from how you start looking for something you might want, through to the tutorial or other detailed explanation which comes with the software. Most of the software is documented by the author for the author, not for the user to whom it is something completely new and needing careful, skillful explanation.

So my experience has been that a lot of the contributed suites are just too "expensive" to adopt --- they take too much time to understand since they are not well explained. (So you end up writing your own instead).

A key component in a system to collect together contributed software is therefore documentation:

- to start with, a meaningful name for the software that tells you what it does.

- a succinctly written abstract which answers the most important questions a user might have when looking for a particular solution.

- cataloging information, such as keywords, which can be used to arrange the software in some kind of organised catalog.

- a clear and simple set of instructions for installing and using the software.

- some kind of longer explanation with examples --- a tutorial.

- a reference --- such as an index of scripts in the suite, or an index of key ideas, and so on.

If people can't easily understand what it is you've created and how it works and how they can benefit from it, then they're unlikely to use it or they will get frustrated in their attempts.

Stop thinking like programmers all the time and learn to think like marketers sometimes --- how do you make your work attractive and useful to someone else?

Regarding the use of xml to describe the contents of a software repository, xml would be an ideal way to encode some of the abovementioned "data structures" so that they could be arranged and presented in meaningful ways.

A useful repository for contributed Frontier software is definitely needed.

There are responses to this message:

This page was archived on 6/13/2001; 4:49:08 PM.

© Copyright 1998-2001 UserLand Software, Inc.