Intro to fSpecs- FAQ

FAQ: Using OLE Tools and understanding documents

The following are some simple definitions and answers to Frequently-Asked-Questions the Core Team and OLE developers have been asked to define throughout the OLE Fspec process. Over time, we will continue to insert additional resources, tips and tricks to this list in response to SME's requests (Subject Matter Experts, i.e. OLE library staff members). To make suggestions for additional content to the FAQ, please email the Core Team, or add comments through the link at the bottom of this page.

This page is under development and content is continuously being added and edited. Please click on any of the questions below to jump to the discussion thread. Many hyperlinks are also connected in the content, and where images are included, click on the image or illustration to see an enlarged view.

1. What is an Fspec?

2. What is a User Story?

3. What do you include in a functional specification?

4. What is the schedule for completing Fspecs?

5. What about technical details? How do we account for system considerations?

6. How do I learn about the other Fspec teams? What other resources are available?

7. I have heard that OLE is being developed using Agile. What does that mean for OLE?

8. Is there training or help available for using Google Docs, Kuali email, and Google Calendars?

9. What tools are provided to help the spec team complete their work?

10. Are the specifications and terminology that have been defined by other teams available for review?

1. What is an "Fspec"?

An F-spec is a "functional specification", or a set of functional library requirements for a specific library process or set of related activities. In OLE, we are isolating our Fspecs per User Story in order to define a small, easily specified set of requirements.

2. What is a User Story?

A user story is a very small, succinct set of functionality written as "As a <role>, I want <action> so that <result>". Examples would be "As a library staff member I need to create a purchase order to order a book.", or, "As a budget officer, I need to modify the fund that is allocated to an account."

3. What do you include in a Functional Specification?

A functional specification can include many things, but focuses on a general description of the work to be done by library users, the data elements or documents affected, and any business rules for managing the work specified. The basic parts of a functional specification may include all or part of the following:

• User Story name, number: An abbreviated name for the user story and a master identifying number (from user story master list).
• Goal: This is the narrative of the user story in a single sentence.
• Summary: Think of the summary like an "abstract". It is a general summary of the completed functional specification in a single paragraph.
• Users: Users can be defined as any person, organization, or system that engages in this requirement or library function.
• Preconditions: Preconditions define all the conditions that must be true (i.e., describes the state of the system or the data or documents) for the trigger to cause the initiation of the User Story.
• Triggers: Triggers describe the event(s) that cause the user story to be initiated
• Author, Date, Version: It is always a good practice to note the author or source and date of the last modification to this document.
• Notes: Include anything else you think we should think about that's not covered elsewhere. Remember: by using User Stories, we are attempting to describe very small pieces of work. Notes are just a place to provide side notes or questions for items of concern.
• Course of events – Workflows: A workflow can be described in a narrative or with a simple illustration of a decision tree/flowchart, with alternative paths and decision points that illustrates the workflow process executed by the User (first do this, then this, then based on a decision, go this way or that way). This is about the user and his or her work process, not dataflows. Think: do.
• Data & Dataflow diagrams: Where does data come from? What is/are required fields/user inputs? What happens to the data - provide a description of how it is transformed. What is the output - what document with what data should be provided at the end of this workflow? Notating or illustrating the dataflows involves describing 1) what data you start with, 2) describe what happens to it (transformations), and 3) what is the end-state of the data or documents involved in the User Story. Think: what document do I have at each step in the workflow, and what data/fields does the document contain?
• Data Models: The OLE data-modeling team has created draft data models and an ERD diagram (Entity-Relationship) for most of Select and Acquire, with some of the data fields defined for further OLE processes. Fspec teams are asked to evaluate the D/M and note any corrections to the assumptions in the model, or merely add any additional fields.
• Alternative paths – Workflows & Dataflows: OLE is interested in documenting the "happy path" or "80%" on workflows or dataflows. Not all universities share the same workflow processes, and we will be able to configure OLE in the future per each site's requirements. Alternative paths may already be included in the original workflow described, in the form of Yes/No decision paths, or alternate paths based on certain criteria (different formats, certain $$ amounts, who is requesting, etc).
• Post-Conditions – Dataflows (documents): Post-conditions can be described in the data model and in the goals of this User Story. Think: what is the document or data I end with that I did not have in the beginning?
• Acceptance Criteria: What are the conditions of satisfaction for this user story? Acceptance criteria can be phrased in the form of a question and answer for the testers to use as a test-script to see if the designed system satisfactorily completes the actions specified in the User Story.

4. What is the schedule for completing Fspecs?

Functional specifications are completed in several phases by the designated Fspec team. While teams are encouraged to be self-organizing, each team will be given deadlines for completing a group of specifications. Upon completion of the final documentation, teams will be requested to be available for some ongoing Q&A with the core team and developers, and then a subset of volunteers will be requested to participate in future testing. A potential schedule could look something like this:

5. What about technical details? How do we account for system considerations?

The specification teams are asked to note any details for technical implementation that they feel comfortable documenting, but the Core Team and Developers are responsible for completing technical detail with the team and/or Technical Council representative through Q&A. Details for Technical Specifications or requirements may include:

• GUI preferences: TBD – List of fields where users can enter information. Where can the user go from here? What should results screen contain?
• Business Rules (Authentication/Authorization): Can insert overview of access (read, write, edit, delete, create, approve).
• Terminology: Description & definitions of domain-specific terminology as to be familiar to stakeholders, and to standardize on language for documentation & testing.
• Functional Details: Can include details about data interfaces, standards, & sources (i.e. use NCIP to populate user record in transactional datastore), interactivity of function (i.e. user-driven function or automated function), security requirements, validation requirement, initial state information (i.e. populate form from document directory based on resource id), etc.
• Acceptance Testing: Per acceptance criteria above, these may be scenarios or tests that can be applied to determine successful outcome of this process.
• Implementation Details: Additional details on programming, Rice, KIM, routines, system interfaces.
• Vendor/System interfaces: This is where we can note any known vendor or system interfaces for dataflows, workflows, financial/university systems.
• Sample Data Sets: For each group of related user stories, Fspec teams may be requested to provide document samples (sample P.O., sample MARC record) and raw sets of sample data (for ingest and varied data standards).

6. How do I learn about the other Fspec Teams? What other resources are available?

Kuali OLE has multiple, simultaneous spec teams working at all times, in order to create an inventory or backlog of specifications ahead of their assignment to scheduled sprints for the developers. By drafting Fspecs in advance, we can organize coding in a logical or sequential fashion, and allow plenty of time for Q&A with spec teams to ensure high-quality development of OLE functionality. The diagram on the right illustrates the organization and cooperation of our teams and resources. More information on overall OLE teams can be found here, or SME's may review the list of Fspec teams and resources.

There are many SMEs available to the Fspec teams, whether it be the Core Team, developers, or members of the Functional or Technical Councils. We also recommend Fspec teams utilize additional resources or expertise within their own libraries – these are the best resources for understanding library process and ensuring OLE is developed as a fully-functioning, reliable, and comprehensive library management system.

7. I have heard that OLE is being developed using Agile. What does that mean for OLE?

The Kuali Open Library Environment project is intended to be developed utilizing an Agile project and software development model. It is characterized by collaboration, adaptation, and efficiency. Teams are to be self-organizing. Development is focused on innovation and incremental "builds" of code and function. Agile is believed to result in higher-quality technical solutions and less lag time, as work is defined into small, incremental units of functionality easily coded within two week sprints. Our exact method is probably a hybrid of traditional or waterfall development methods and agile, but we seek to blend the best practices of Agile development and scrum into our approach. For more information, see: Woodward, Elizabeth, 1965 - Title: A practical guide to distributed Scrum [electronic resource] / Elizabeth Woodward, Steffan Surdek, Matthew Ganis. Published: Upper Saddle River, NJ : IBM Press, 2010 (Norwood, Mass.) : Books24x7.com.

8. Is there training or help available for using Google Docs, Kuali email, and Google Calendars?

There are several tools available to users of Google Docs, Kuali email, and the Google Calendars used by Kuali OLE to manage our team documentation, communications and scheduling.

Google Docs:

Google Docs offers video tutorials, formatting assistance and discussion threads to answer common questions. Below are some tips for common OLE tasks too.

Page Refresh: Google Docs will sometimes show only partial lists of documents. It's particularly frustrating when you know a document is in the file. Please click on your browser's refresh button to see a full folder view.

Mapping "My Collections": When you first open Google Docs, your left menu will not display any OLE file folders - only those owned by you. In order to map OLE folders into your "My Collections", please use these to map the OLE project folders. You only have to do this once, and then Google Docs navigation will be much easier. Alternatively, you can "star" the "Kuali Shared" and "OLE" folders if used infrequently, and only add to "My Collections" the individual folders you might use on a regular basis.

Sharing Documents or Folders: When creating a new document, Google Docs sometimes defaults to a saved location in your personal space "Owned by me" or "Home". Likewise, when uploading documents, the default setting is "private" and will also load to your personal folders. If you've accidentally loaded or saved files to your personal folders, you may drag and drop them into the correct folder. Documents will generally inherit the permissions of the parent folder they reside in. However, if you need to make sure that everyone who needs to see the document you've created has permissions, please check the box next to the file, and click on button/menu above to select Share>Sharing Settings (or right click on file or folder, and select "share"). First search the list of people and groups who already have "Sharing", and then you may enter email addresses or KIS OLE distribution lists in the "Add People" box to share your document or file. Before clicking on the "share" button at the bottom of the pop-up window, be sure to select whether you want the people you are adding to edit (default) or merely be able to view document. Google Docs also defaults to "send email notification", so you'll want to un-check that box if you do not want an email to go out to all the people or groups you've added. Similarly, in this same pop-up window, you may delete or edit groups from seeing your document if you wish to make it private.

Real-time editing & sharing: Google Docs provides real-time sharing of documents. When multiple users have a document open, you can see other users' edits highlighted with different colored cursors in the document. If you see a "sharing" window in the upper right of an open document, you can click the down-arrow to the right of the name to see all those users logged into the document. With this expanded right sidebar, you can enter into chat too.

Collapse or Hide Controls: From the view menu, you can increase your screen's view vertically by selecting "compact controls" and "full screen" to eliminate the uppermost Google headers and menus and show you more of the open document. (See the example on the right)

Google Calendar:

Please refer to the online for tutorials and discussion threads. You may also create additional calendars, or access other Kuali OLE Team calendars. Open one of the linked OLE calendars, and click on the +Google Calendar button in its lower right corner to add it to your "Other Calendars" view. It is especially helpful if you add the or your spec team's calendar to your personal calendar window, so that you may schedule activities, or copy meetings from one calendar to another. Note: if you set up a meeting in a team calendar, you cannot send from it unless you are authorized. It is often easier to setup a meeting in your own calendar and mail an invite to the distribution email of the team. For the you can reserve conference lines, but not invite attendees - the message may show up in invitee's Kuali inbox, but these invites that are direct from Team calendars often do not forward to your primary mail client.

Kuali Email:

Everyone in Kuali that has KIS credentials will also have a Kuali email address (_____@kuali.org). You may synch your Kuali email with your primary email client by using the help center for your specific application. Please note: some scheduling notifications or calendar reminders that originate in your Kuali calendar and email may not forward to your primary email client. Be aware of this and check your Kuali email periodically. Please refer to the

9. What additional tools are provided to help the spec team complete their work?

The core team is making available a number of items at the kickoff of each new spec team and specification effort, as included in the Facilitator's Guide. These items may include:
Specification Roadmap (overview of team charges and team members); A related list of functional user stories grouped into workflow order; Team KIS page with calendar, resource links, contact names & emails; Team email distribution address; KIS credentials for new OLE members; Google Docs team folder; data model and data entities draft for review; any available workflows that have been drafted; pre-seeded specification templates; link to sample completed specification; any related KFS functional documents; and, additional resources as identified.

10. Are the specifications and terminology that have been defined by other teams available for review?

The specifications of all Fspec teams are available for review and comment via or as reference in the completion of future specifications. In addition, we are also compiling a library for use by and between all functional and specification teams, so that we share common understanding of terms, and can share those with developers.