[FM Discuss] Mifos manual ready for first review

[Adam Monsen]

Are you ready to rock?!

I'm Adam, a software developer on Mifos. We are fighting suffering with
the careful application of technology that rises people out of poverty.

We've been taking full advantage of the awesomeness of FLOSS Manuals. If
you're ready now, we need you!

Will you help us perfect our manual? Please see Anita's note below for
specifics.

One additional comment. Anita urges people to look out for
"...duplication of material. It's tempting to have procedures at the top
level for functions that we (or somebody) thinks is popular and likely
to be used--and for those to duplicate other procedures that are buried
in the UI organization. Duplication means that there are possibilities
for mismatches; it's also a maintenance hit if that procedure ever
changes."

If you're helping and have Mifos-specific questions, please ask them in
the #mifos IRC channel (on FreeNode) or on our "users" mailing list. Or
here, I suppose, if they're on-topic.

Thank you Anita Anderson and Mike Dash for kicking off our manual!
Thank you Anne Gentle, Edward Cherlin, and Cara Bell-Jones  for helping
us get started!
Thank you to the folks who maintain FLOSS Manuals and nurture this
amazing community!

I heart you.


-------- Forwarded Message --------
From: Anita Anderson
Subject: MIFOS 1.5 docs ready for first review
Date: Tue, 16 Mar 2010 15:19:23 -0700

Greetings, review team--

The (very rough) first draft of MIFOS 1.5 docs is now ready for your
review.

Please note: Our schedule requires a very quick (like 24 hours) review
on your part to make our deadlines. I know that you have workshops in
addition to your regular work, but please make every effort to complete
your review ASAP.

This is a long message, unfortunately. Please read it all the way to the
end; this will make your review more efficient.

General organizational issues

The current doc set, as per the outline you approved, is organized by
the UI, not by roles or by detailed lists of functions. The left nav TOC
(called "index" by FLOSS folks) can only be two levels deep.
Furthermore, FLOSS does not allow any interior hyperlinking in a chapter
or a manual--that is, I can't refer readers to instruction in another
area by giving them a live link to that section. And some tasks are many
levels down in the organization of the UI, particularly those on the
details pages.

Therefore, in an effort to help readers find specific task information,
I have created a chapter called "Common tasks." This connects tasks with
chapter titles. This is not a very satisfactory solution, because the
names of chapters are static; this list must be maintained by hand and
will quickly go out of date if any chapters are deleted, reorganized, or
renamed. However, it's the best that can be done with FLOSS limitations.

Right now, this chapter includes all tasks that can be isolated. (If
this were a conventional help system, this would be the complete list of
all topics.) Clearly, this is too much. Furthermore, some tasks have a
1:1 relationship with their chapter titles, and including them is a
waste of space. I rely on you to tell me which tasks to retain in this
chapter; I expect that the ones buried in the details pages are prime
candidates, but I await your judgment on this.

You will also see occasional references in the text to specific chapter
titles, when I couldn't think of another way to do it. These will also
be a maintenance hit, unfortunately.

What to read for

Completeness: Have I covered all functions, and all steps in each
function? Is there further material (especially about the reasons for
using certain functions, or the consequences of making certain
decisions) that could be added? (I have a note to include information on
LSIM and non-LSIM groups, but I see nothing in the UI about this. Where
would I discuss this, and what information can I get?)

Tone: Is everything expressed in plain-enough English? Can you suggest
some simplifications that would help here?

Accuracy: Does the UI work exactly as described? Are some functions
showing in the test server (which I have used as a reference) actually
configurable and thus not always as described?

Questions: These are scattered throughout the text. Some functions
didn't work fully, as far as I could tell; some functions I couldn't
access. Please address these; if you don't know, tell me who does know.

Typos, grammatical errors, etc.: I hope there are none of these, but
inevitably there will be. There are also judgment calls: should I use
the British spelling of "centre" throughout, for example? Right now it's
mixed.

What to ignore

Screenshots: In every possible situation, I have taken screenshots of
empty pages, and I have these stored locally. I have put placeholders in
the text to show where these will appear. Empty screenshots are only of
limited use, and some of them have test data (like KAYTEST#3) that we
wouldn't want readers to see. What needs to happen next is that I get
access to a dataset (the Filipino one has been suggested) with a good
variety of data for screenshots that show how pages can be filled out.
When these improved screenshots are taken, all of them must be processed
through Photoshop to have borders put on them. Depending on time and
access, I will attempt to do all this--but translation could proceed
even before all of these are done.

Formatting: As far as I can tell, FLOSS does not allow me to put a
bulleted list in the middle of a procedure and then continue with the
procedure's numbered steps in order. I assume this renumbering will have
to be done manually in source view. You will see the FIX NUMBERING
notation in several places.

Glossary: Virtually no work has been done on the glossary; a volunteer
offered to help, but I haven't seen any results yet. Mike Dash may also
be contributing to this.

Tips and techniques/Best practices: You'll see a few of these, but I'm
relying on people like Ryan to provide more. If you have any, by all
means add them in the appropriate places.

How to make your comments

Using your FLOSS credentials, log on at 

http://en.flossmanuals.net/bin/view/Mifos/

You'll see a list of chapters organized by category. (The chapters at
the bottom are early ventures and leftovers that I haven't figured out
how to delete. Ignore them.) 

To read the chapters, click their link; to edit them, click the Edit
link. When you Save the chapter, I will see a diff display showing me
who made what changes. 

Thank you for all your input. This is a difficult assignment for us all,
including a venture into unknown open-source documentation territory,
with a very short schedule. All help is welcome. And remember: silence
is assent. If you don't change it, it will be published as is.

A second review is scheduled. At that time, you can check to see that
your comments are included, view the comments of others, and make any
last-minute changes.

I will be continuing to work on the docs as you are reviewing.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20100317/0229cd89/attachment.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20100317/0229cd89/attachment.pgp>