[FM Discuss] Help, Advice, Tips for a project documentation.

[Andy Oram]

I spent a little time creating a demo project and browsing the guide
in its current state. Your documentation is in a very typical state
for new projects attracting early adopters. Your first "users"
(terrible term, but we haven't found a better one yet) know project
management already, have probably used other tools already to
accomplish project management, and are familiar with--or unfazed by
the need to learn--basic data entry skills such as setting up an
account and navigating tabs.

I'll return later to your early adopter audience, but you probably
want to leap to the next stage where you attract people who are not so
familiar with other project management tools. They may be project
managers, but are doing a lot of wasteful ad hoc management and
missing important tasks. For these, you need background documents that
lay out what project management is and link its tasks to your
features.

In this regard, the FLOSS Manuals CiviCRM book
(http://en.flossmanuals.net/civicrm), which has just undergone a
second revision in a sprint, is worth a close look. The organizers of
the sprint knew that they had plenty of documentation in the
traditional "This is what the product offers" style, but what they
eeded was a guide linking real life to product features. The book has
a large Planning section near the start and Planning chapters to begin
the discussion of each module.

Chepi Gimenez's advice on this list is useful for developing
step-by-step documentation, but that won't be enough to get people
using your project or ensure they use it in the best way. I think
there's something subtle along these lines in Janet Swisher's advice,
which I'll expand on. She recommends you focus on user tasks. But the
concept of "task-oriented" can be misleading because there are many
layers of viewing tasks. A very rudimentary task is "How to report the
changes made on an issue," which can be explained in a step-by-step
tutorial. A more sophisticated approach to tasks might be "How to
determine whether you're getting satisfactory progress," which is a
whole different approach to learning and not as easy to explain.

Your forums have a lot of activity that you can capitalize on. I
assume you check the forums and generate your FAQ from issues that
come up there regularly. You could try organizing the forums more
around the FAQ, because in my opinion the forums are a bit too
disorganized. Someone who follows a mailing list can respond to the
most recent postings and follow a current discussion. But the archives
are hard to scan casually later as a source of information. I have a
couple articles that might stimulate some ideas for organizing the
forums and FAQ:

  http://radar.oreilly.com/archives/2008/01/two_tools_we_ne.html
  Two tools we need to improve online information

  http://radar.oreilly.com/archives/2008/02/developing_an_i.html
  Developing an improved online environment for educating computer users

Back to early adopters. You can still do more to attract and keep
them. You need to explain how Redmine is unique and what it offers
that would make them want it. A list of features is dull. The features
page (http://www.redmine.org/wiki/redmine/Features) is a good start,
but you should still expand it with more explanations. For instance,
how do certain offerings such as custom fields allow people to meet
needs that you didn't anticipate?

You could have a whole section about extendability, ranging from
custom fields to your API. You probably know the value of an API
because you're always looking at possibilities to extend your utility
anyway. But remember that the API essentially recruits outside
developers to add new features that enhance the value of your
utility. By writing documentation that illustrates the new things they
can do, you may win over important allies.

-- 
----------------------------------------------------------------------
Andy Oram  O'Reilly Media                     email: andyo at oreilly.com
Editor     10 Fawcett Street, Fourth Floor         voice: 617-499-7479
           Cambridge, MA 02138-1175, USA             fax: 617-661-1116
           identi.ca/twitter:praxagora http://www.praxagora.com/andyo/
----------------------------------------------------------------------