[Booki-dev] notes to meeting

Wed Jul 28 09:11:21 PDT 2010

hi Frank,

It was good to meet you and Im glad Source Fabric is considering working
with us and you to develop features they and we need (Aco is also keen
for this). 

I have sent this email to the dev list and to you and micz. It might be
good for you both to consider joining the list.
http://lists.flossmanuals.net/listinfo.cgi/booki-dev-flossmanuals.net

Below the content of this email is a very basic requirements doc. It does not
outline the notes tab, so I thought I would make some notes here for
your (and Miczs) consideration should Source Fabric decide they wish to
commission all or part of this development. 

In essence, I think that the notes tab could nest the following:
1. To do list
2. Book notes
3. Style guide

these could be hidden via a drop down or accordian style interface. Our
plan is to keep everything as simple as possible so I would imagine a
page with three headings and clicking on each reveals the information
behind it.

Some ideas:
1. To do list
The basic form could be a JQuery to do as we looked at today:
http://demo.tutorialzine.com/2010/03/ajax-todo-list-jquery-php-mysql-css/demo.php

If this is the format it would be good enough as it is. The good news is
that this is done using JQuery so I imagine this is a very easy
implementation. What you would need to work out however is how Aco
implements the dynamic updates so that when a to do is altered everyone
has that info updated.

If there was room to take this development a step further i would
recommend considering adding the following fields:
* assigned to
* due date
* priority

I am not married to those ideas though as I think we need to insure that
the interface does not have too much things going on. So I would
actually recommend we start with the basic implementation and move on.
When users have tried it then we can consider extending it with these
items.

2. Book Notes
Something like etherpad would be good but too complex (see.
http://piratepad.net/ )
I would suggest considering either a) the same interface as we have now
in the notes pad except with a very very simple WYSIWYG or b) a threaded
comment system. I think the best would again be to do the easiest and
simplest - what we have now with a WYSIWYG interface (and no need to
press 'save'). Then when users use it we extend according to demand for
most-needed features. 

3. Style Guide
This is pretty much the same as (2) except it would be used for storing
the Style Guide. A style guide is optional but many people request it in
FLOSS Manuals and some go out of their way to create one so I think this
would be a very good feature to anticipate based on our user experience
so far.

I think all of the 3 above are simple and i think Source Fabrics working
process (especially for the forthcoming sprints) would benefit a lot from them.

You might have noticed that I prefer to take the easy road for features, leaving as
much open as possible, and then refine according to use. That is because
from experience I have learned that when designing software it is better
to be led by the user rather than force them into an imagined work flow.
It has worked well for us so far - everything you now see in Booki is
pretty much that way because we have tried similar ideas in FLOSS
Manuals and seen their effect. I would prefer to continue to work this
way with Booki. 

So...there was one more feature we discussed - Chapter Level notes. I
think this would be extremely useful for Source Fabric (but micz needs
to comment on this) but we need to be careful that we get it right
because it is not so obvious how this might work. 

I think the notes have to be associated with the chapter page when you
edit it - however there is very little space there. One possibility is to
build this into the WYSIWYG editor - Xinha - as a 'notes server' or some
such. ie. it opens from the WYSIWYG editor but stores the content
(chapter notes) in the booki db. The risk here is that people will not
know that the notes are there...so we need to consider this. Another
possibility is to build this into a 'sliding tab' as Micz suggested. I
think that might be ok but it would have to be done carefully as it
might look too much like a gimic.

The other issue with chapter level notes is that I strongly believe that
an overview of all chapter notes for a book should be able to be seen
somewhere, in one place. Otherwise it would mean checking each chapter
which would be a tedious job (books easily have 30+ chapters). So if you
consider Chapter notes then you must also consider how to do this. 

So on this I am not so clear what would work well for Chapter level
notes and because of this I think its not such a good feature for our
first adventure working together. I would recommend instead the first
three to be done all together - however this is up to Micz.

My feeling is that the first 3 are an extremely quick development, first
however you need to know how it all fits together so i would suggest
emailing this list when you have questions and I am sure Aco will answer
your questions...

Also, Aco is currently working on the Booki site update so I expect the GIT
repo is not updated but will be within the next days once the booki www
is updated....

also you should meet Doug - doug is on this list and he is the Objavi
(PDF generator) developer....doug - frank, frank - doug

also, meet John who does the Booki manual and other essential tasks - intro intro :)

:)

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 (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.14 Edit Tab
Status: High Priority, Implemented
Function: Edit interface for chapters.
Interface: Clicking ´edit´ on a chapter title will open the Xinha
WYSIWYG editor with the content in place. 

3.1.15 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.16 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.17 Export Tab
Status: High Priority, Implemented
Function: Export content to various formats
Interface: User clicks on the Export tab and is presented with a form
for choosing export options. Clicking "Export" returns the desired
output for download. 

3.1.18 Version Tab
Status: High priority, Not Implemented
Function: can easily freeze content at stable stages while work
continues on the unstable version.
Interface: 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 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.20 Chat
Status: High priority, Implemented
Function: A real time chat (web / IRC gateway).
Interface: Persistent on the edit page for any book. 

3.1.21 Localisation
Status: High priority, Not Implemented
Function: Booki needs to be available in any language where it is
needed. Hence we may integrate the Pootle code base into Booki to enable
localisation of the environment.
Interface: TBD

3.1.22 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.23 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##"
Note: should be a syntax for producing Attribution notes on a
per-chapter basis eg. "##CHAPTER-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. 