On Tue, 2010-06-29 at 07:43 -0700,
tosmaillist.neophyte_...@ordinaryamerican.net wrote:
> On Tue, Jun 29, 2010 at 6:03 AM, adam - a...@xs4all.nl wrote:
> > hi,
> ><snip>
> >
> > So...moving forward - I welcome a review of potential tools for TOS and
> > we would certainly like to make TOS aware of Booki. If there will be a
> > formal process perhaps this should be outlined, otherwise I can email
> > something to the list (and I hope others do too with other suggestions).
> >
> > adam
>
> Perhaps, adam, you could lead us to the requirements documents for
> booki and we could leverage that for our discussion here?
ok...I haven´t written a Requirements doc before so here is my first
attempt. I put it together from existing docs we have. It should give
you and idea of Booki but it is by no means a complete document. Any
feedback is appreciated on the ideas behind Booki and also the structure
and content of the doc.
adam
1 INTRODUCTION
1.1 Description
Booki is designed to help you produce books, either by yourself or
collaboratively. A book in this context is a `comprehensive text´ which
can be output to book formatted PDF (for book production), epub, odt,
screen readable PDF, templated HTML and other formats.
Booki supports the rapid development of content. Booki has tools to
support the development of content in 'Book Sprints'. Book Sprints are
intensive collaborative events where collaborators in real and remote
space focus on writing a book together in 3-5 days.
While you can use Booki to support very traditional book production
processes, the feature set matches the rapid pace of publishing possible
in the era of print on demand and electronic readers. Booki can output
content immediately to multiple electronic formats. Print ready source
(book formatted PDF) can be immediately generated, and then uploaded to
your favorite Print on Demand (PoD) service, taken to a local printer,
or delivered to a publisher.
1.2 Purpose
Booki embraces social and collaborative networked environments as the
new production spaces for comprehensive text (book) content.
1.3 Scope
Booki is available online as a networked service (http://www.booki.cc)
for free. This service is a production tool for the creation of free
content and not a publishing/hosting service. Content produced within
Booki.cc is intended to be published elsewhere, either under another
domain, in paper form (ie. books), distributed in electronic formats, or
re-used in other content.
Booki can be installed by anyone wishing to utilise this software under
their own domain or within private or local networks.
2 OVERALL DESCRIPTION
2.1 Product Perspective
Booki takes what was learned from building the FLOSS Manuals tool set
and posits these lessons within a more suitable architecture.
Booki is the name of the collaborative production environment, however
there are 2 associated softwares that provide all the services
required :
* Booki - production environment
* Objavi - import and export engine
This document refers to Booki 1.5 and Objavi 2.2
2.2 Booki Functions
* User account creation requiring minimal information
* One click book creation
* Drag and drop Table of Contents creation
* One click editing of chapters
* Chapter level locks
* Live chat on a book and group level
* Live book status reports (editing, saving, chapter creation) delivered
to the chat window
* Drop down chapter status markers
* One click to join a group
* One click to add a book to a group
* One click exporting to epub, screen pdf, book formatted pdf, odt, html
with default templates
* Easily accessible advanced styling options for export (CSS controlled)
* User profile control (status, image, bio)
* One click group creation
* Easy importing of book content from Archive.org, Mediawiki, other
Booki installations
* Option to upload content to Archive.org
2.3 User Characteristics
2.3.1 Contributor
The majority of users will be contributors to an existing project. They
may contribute to one or more project and may produce text and/or
images, provide feedback or encouragement, proof, spell check, or edit
content. These are the primary users and the tool set should first meet
their needs.
2.3.2 Maintainer
These are advanced users that create their own books or have been
elevated to maintainer status for a book by group admins. Maintainers
have associated administrative tools for the books they maintain which
are not available to other users.
2.3.3 Group Admin
These are advanced users that wish to establish and administrate their
own group. They have maintenance tools for every book in their group
plus additional group admin tools.
2.4 Operating Environment
Booki is designed primarily for standards based Open Source browser
comparability but is tested against other browsers.
2.5 General Constraints
* Booki and Objavi are Python based.
* Booki is built with the (bare) Django framework.
* Booki uses JQuery for dynamic user interface elements.
* Booki uses Postgres as the database but sqlite3 can also be used
* Redis is used by Booki for persistent data storage to mediate dynamic
data delivery to the user interface
* Objavi utilises Webkit for PDF generation. Later Gecko will be added.
* Rendering of .odt by Objavi requires OpenOffice to be installed with
unoconv.
* The Booki Web/IRC gateway may eventually (and optionally) require a
dedicated standalone IRC service hosted on domain.
* Content editing in Booki is done by default with the Xinha WYSIWYG
editor
* XHTML is the file format for content.
* Content will be ultimately be stored in GIT.
* Localisation in Booki is managed with Portable Object files (.po).
* The code repository for both projects is GIT with a dedicated Trac for
bug reporting and milestone tracking :
http://booki-dev.flossmanuals.net
* A Dev mailing list is maintained here:
http://lists.flossmanuals.net/listinfo.cgi/booki-dev-flossmanuals.net
* Developers can be reached in IRC (freenode, #flossmanuals)
* Each release will be as source. Beta and later releases will also be
available as Debian .deb packages.
* User and API Documentation will be maintained in the FLOSS Manuals
Booki Group.
* For development we use Apache2 for http delivery
* The license is GPL2+ for all softwares
2.5 User Documentation
Maintained here : http://www.booki.cc/booki-user-guide/
3 SYSTEM FEATURES
3.1 Booki Features
3.1.1 Booki-zip (Internal File Format)
Status: High Priority, Implemented
Function: A Booki-specific file structure for describing books
Interface: Used for internal data exchange between Booki and Objavi.
Notes: booki-zip definition maintained here :
http://booki-dev.flossmanuals.net/git?p=objavi2.git;a=blob_plain;f=htdocs/booki-zip-standard.txt
3.1.2 Account Creation
Status: High Priority, Partially Implemented
Function: Quick access to a registration form from the front page for
account creation
Interface: Requires only username, password, email and real name
(required for attribution). Email is sent to the user with autogenerated
link for verification
Notes: email confirmation mechanism missing
3.1.3 Sign in
Status: High Priority, Implemented
Function: Quick access to a sign-in form from the front page
Interface: Username and Password form and submit button. Username and
pass remembered.
3.1.4 Profile Control
Status: Medium Priority, Implemented
Function: When logged in the user can access a profile settings page to
set personal details (email, name, bio, image). Personal details can be
browsed by other users
Interface: "My Settings" link in user-specific menu on left gives access
to a form for changing the details.
3.1.5 Book Creation
Status: High Priority, Implemented
Function: Users can create a book from their homepage ("My Profile").
Interface: User can click on "My Profile" link from the user-specific
menu on the left. On the Profile page a text field for the name of the
book, and a license drop down menu (license *must* be set) is presented.
Clicking on "Create" adds the empty book with edit button to the listing
of the users books on the same page.
3.1.6 Archive.org Book Import
Status: Medium Priority, Implemented
Function: Users can import books from Archive.org
Interface: "My Books" link in the user-specific menu on the left
presents the user with a field for inputting the ID of any book from
Archive.org. The book is then imported when the user clicks "Import".
Notes : Interface is through Booki but Objavi does the importing and
returns Booki zip to Booki. Relies on Archive.org successfully
delivering epub for each book but this is not always happening. Needs
error catching and user friendly progress/error messages.
3.1.7 Wikibooks Book Import
Status: Medium Priority, Implemented
Function: Users can import books from Wikibooks
(http://en.wikibooks.org)
Interface: "My Books" link in the user-specific menu on the left
presents the user with a field for inputting the URL of any book from
Wikibooks. The book is then imported when the user clicks "Import".
Notes : Interface is through Booki but Objavi does the importing and
returns Booki zip to Booki. Needs thorough testing as it is sometimes
failing possibly due to time-outs. Needs error catching and user
friendly progress/error messages. Should be extended to be a "mediawiki
import" tool, not just for Wikibooks.
3.1.8 Epub Book Import
Status: Medium Priority, Implemented
Function: Users can import any epub available online
Interface: "My Books" link in the user-specific menu on the left
presents the user with a field for inputting the URL of any epub. The
book is then imported when the user clicks "Import".
Notes : Interface is through Booki but Objavi does the importing and
returns Booki zip to Booki. Needs thorough testing as it is sometimes
failing possibly due to time-outs. Needs error catching and user
friendly progress/error messages.
3.1.9 Group Creation
Status: High Priority, Implemented
Function: Users can create groups.
Interface: "My Groups" link in the user-specific menu on the left
presents user with 2 text fields - group name, and description. When a
name for a group is entered and "Create" is clicked then the group is
created.
Notes: Group admin features missing.
3.1.10 Joining Groups
Status: High Priority, Implemented
Function: Users can join groups with one click.
Interface: "Groups" link in the general menu on the left presents a list
of all Groups, by clicking on link the user is transported to the
homepage for that group. At the bottom of the page the user can click
"Join this group" and they are subscribed.
3.1.11 Adding Books to Groups
Status: High Priority, Implemented
Function: Users can add their own books to groups they belong to.
Interface: While on a Group page that the user is subscribed to the user
can add their own books to the group.
Notes: When Group Admin features are in place we will change this so
that Group Admins set who can and cannot add books to groups. At present
a book can only belong to one group.
3.1.12 Readable Book Display
Status: High Priority, Implemented
Function: Users can read stable content in Booki without the need to
log-in.
Interface: Upon clicking on the "Books" link in the general menu on the
left a page listing all books is presented. Clicking on any of these
presents a basic readable version of the stable content. Alternatively
users can link to a book on the url http://[booki install domain]/[book
name]
3.1.13 Edit Page
Status: High Priority, Implemented
Function: Page for editing content.
Interface: The edit page is accessed by clicking on "edit" next to the
name of a book in "My Books" or "Books" (all books) listings. The user
is then presented with a page with tabs for : editing, notes, exporting,
history
3.1.1 Edit Tab
Status: High Priority, Implemented
Function: Edit tools and TOC management tool.
Interface: Table of Contents can be created by clicking "Add Chapter" or
"Add Section" and dragging and dropping these elements in the
appropriate order. Clicking on the title will make the title editable.
Clicking edit on a chapter title will open the Xinha WYSIWYG editor with
the content in place.
3.1.14 Notes Tab
Status: High Priority, Implemented
Function: A place for contributors to keep notes on the development of
the book
Interface: User clicks on the Notes tab for a book and is presented with
a shared notepad for recording issues or discussing the development.
Notes : Implemented but future direction TBD
3.1.15 History Tab
Status: High Priority, Implemented
Function: Shows edit history of the book
Interface: User clicks on the history tab and can see the edit history
with edit notes.
Notes: Implemented but unreadable. Users should also be able to access
diffs here.
3.1.16 Export Tab
Status: High Priority, Implemented
Function: Shows edit history of the book
Interface: User clicks on the history tab and can see the edit history
with edit notes.
Notes: Implemented but unreadable. Users should also be able to access
diffs here.
3.1.17 Subscribe to edit notifications
Status: High Priority, Not Implemented
Function: Users can subscribe to edit notifications
Interface: User clicks "Subscribe to edit notifications" from the Edit
Page for a book. If there are edits made a synopsis is emailed with
basic edit information (time, chapter, person who made the change,
version numbers) and a link to the diff.
3.1.18 Versioning
Status: High priority, Not Implemented
Function: Maintainers can easily freeze content at stable stages while
work continues on the unstable version.
Interface: Details TDB : basic idea is that from the Edit Page a
maintainer sees an extra tab "Version". From here a maintainer can click
"create stable version" - the last stable version is archived recorded
and the current version becomes the new stable version.
3.1.19 Chat
Status: High priority, Implemented
Function: A real time chat (web / IRC gateway).
Interface : Persistent on the edit page for any book.
3.1.20 Localisation
Status: High priority, Not Implemented
Function: Booki needs to available in any language where it is needed.
Hence we will integrate the mature Pootle code base into Booki to enable
localisation of the environment.
Interface: TBD
3.1.21 Translation
Status: High priority, Not Implemented
Function: Content can be forked and marked for translation. A
translation version of a book will provide link backs to the original
material, be placed in a translation work flow, and edited in a
side-by-side view where the translator can also see the original
source.
Interface: TBD
3.1.22 Copyright Tracking (Attribution)
Status: High Priority, Implemented
Function: Any user contributions are recorded and attributed.
Interface: All attributions are automated in Booki. Book level
attribution is output in any chapter that contains the string
"##AUTHORS##"
3.2 Objavi Features
3.2.1 Book Formatted PDF Output
Status: High Priority, Implemented
Function: the server side creation of Book Formatted PDF is a pivotal
feature. This is managed by Objavi which runs as a separate service. The
book formatted PDF supports Unicode, bi-directional text, and reverse
binding for printing right-to-left texts on a left-to-right press and
vice versa. The formatting engine outputs customisable sizes including
split column PDF suitable for printing on large scale newsprint.
Interface: This feature is managed by Objavi, an API is functional and
feature rich but not well documented at present. Objavi also presents a
web interface for those wanting more nuanced control (see
http://objavi.flossmanuals.net/).
3.2.2 CSS Book Design
Status: High Priority, Implemented
Function: The default PDF rendering engine for Booki is now Webkit and
will eventually be Mozilla Firefox hence there is full CSS support for
creating book formatted PDF in Booki. This changes the language of
design from Indesign to CSS – which means any web native can control the
design of the book.
3.2.3 Export Formats
Status: High Priority, Implemented
Function: Users also can export to self contained templated (tar.gz)
HTML, to .odt (OpenOffice rich text format), epub, and screen readable
PDF. Other XML output options can be developed as required.
---
I hope this adds something to the conversation.
Adam
>
> Is there anyone here who works with The Linux Documentation Project
> and could point us to their requirements document, if any?
>
> Are there any other users of other documentation environments that
> could point us to similar requirements specifications for what they
> use?
>
> If there are no special requirements specifications on the projects
> for which you develop documentation, perhaps you can describe the work
> habits of the group for us?
>
> I'm interested in finding how well group dynamics are managed by the
> various existing documentation environments. I think Matthew Jadud
> had a valuable insight with his comments about a wiki approach.
> Parallel efforts that can be compared and contrasted, yet controlled
> until consensus is achieved is a key feature of cooperative
> development in my world view.
>
> _______________________________________________
> tos mailing list
> tos@teachingopensource.org
> http://teachingopensource.org/mailman/listinfo/tos
_______________________________________________
tos mailing list
tos@teachingopensource.org
http://teachingopensource.org/mailman/listinfo/tos
