<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 TRANSITIONAL//EN">

<HTML>

<HEAD>

  <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=UTF-8">

  <META NAME="GENERATOR" CONTENT="GtkHTML/3.28.1">

</HEAD>

<BODY>

<I>Are you ready to rock?!</I><BR>

<BR>

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

<BR>

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

<BR>

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

<BR>

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."<BR>

<BR>

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.<BR>

<BR>

Thank you Anita Anderson and Mike Dash for kicking off our manual!<BR>

Thank you Anne Gentle, Edward Cherlin, and Cara Bell-Jones  for helping us get started!<BR>

Thank you to the folks who maintain FLOSS Manuals and nurture this amazing community!<BR>

<BR>

I heart you.<BR>

<BR>

<BR>

-------- Forwarded Message --------<BR>

<B>From</B>: Anita Anderson<BR>

<B>Subject</B>: MIFOS 1.5 docs ready for first review<BR>

<B>Date</B>: Tue, 16 Mar 2010 15:19:23 -0700<BR>

<BR>

Greetings, review team--

<BR>

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

<BR>

<I>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.</I>

<BR>

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

<BR>

<B>General organizational issues</B>

<BR>

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.

<BR>

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.

<BR>

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.

<BR>

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.

<BR>

<B>What to read for</B>

<BR>

<I>Completeness</I>: 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?)

<BR>

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

<BR>

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?

<BR>

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.

<BR>

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.

<BR>

<B>What to ignore</B>

<BR>

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.

<BR>

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.

<BR>

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.

<BR>

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.

<BR>

<B>How to make your comments</B>

<BR>

Using your FLOSS credentials, log on at 

<BR>

<A HREF="http://en.flossmanuals.net/bin/view/Mifos/">http://en.flossmanuals.net/bin/view/Mifos/</A>

<BR>

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.) 

<BR>

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. 

<BR>

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.

<BR>

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.

<BR>

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

<BR>

</BODY>

</HTML>