[FM Discuss] Mifos manual ready for first review

[Edward Cherlin]

I have been sick for the last week, but I am able to work on the Mifos
Glossary today. I will start by going through the text looking for
words and phrases to add to the Glossary. I will add the definitions I
know, and ask for help with others.

On Thu, Mar 18, 2010 at 00:47, Adam Monsen <haircut at gmail.com> wrote:
> 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.
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>
>



-- 
Edward Mokurai (默雷/धर्ममेघशब्दगर्ज/دھرممیگھشبدگر ج) Cherlin
Silent Thunder is my name, and Children are my nation.
The Cosmos is my dwelling place, the Truth my destination.
http://www.earthtreasury.org/