awmartin / doctoral Goto Github PK

Motivation

As an author, sometimes I need to write with a narrower window, and I expect the editor layout to adjust to fit the size of my browser window.

Design + Acceptance Criteria

• Wide view, 1600px+, keep current layout.
• Medium view, have the doc editor float over the headings. When hovering over the headings, make them pop up over the doc editor. Consider collapsing the right-hand margin.
• Smaller, collapse the sidebar with a button. Clicking the button reveals the sidebar.

Motivation

Firebase is a great platform, but it still relies on managed hosting by "someone else."

Providing another backend in Node.js and a NoSQL database enables authors to host their own deployment locally to keep their documents private, or to deploy on their own remote servers, or even Cloud Foundry, Heroku, etc., if they so choose.

This can also enable offline use cases.

Acceptance

I can use the same front-end code (deployed with yarn serve) and specify the ExpressMongoBackend. After starting the server locally, I can create/modify/delete documents just like with Firebase.

Notes

First implementation has no authentication. It just assumes the server is running locally and MongoDB is deployed with default settings.

Using MongoDB Community v4.2 to start.

To further separate front-end from backend-code, let's isolate the Firestore-specific code. This also enables the possibility for other backends like Node.js/Express + MongoDB or Redis or whatever.

Creating docs and folders don't use the right Firestore-provided protections against failures, since multiple entries need to be created. Go ahead and use them.

Observed Behavior

When creating headings in a doc and styling them with highlights, the HTML for the highlight appears in the headings outline on the left. e.g. <mark class="pen-red">.

Desired Behavior

The heading text in the outline should just be the text reflected in the heading in the document body, with no HTML artifacts.

Reproduction Steps

1. Create a heading in a doc by selecting and picking "Heading 1" or similar in the toolbar.
2. Select the heading (or a portion of the heading) and add a highlight.
3. Observe the outline entry on the left has HTML in it.

Observed Behavior

When HTML characters (e.g.  ) appear in headers, they show up in the headers outline on the left as escaped characters.

Impact of observed behavior

Looks really weird and gives an impression of instability in the app.

Desired Behavior

Those characters should be there in the outline, but they shouldn't be escaped, they should be the character they're intended to represent.

Reproduction Steps

1. Create a header. Observe the header appearing in the outline.
2. Delete the text in the header by pressing backspace.
3. Navigate the cursor away from the header.
4. Observe the header in the outline now appearing as  

Anticipated Fix

There may be a way in Vue.js to not escape contents that are interpolated into the template during rendering.

Motivation

When reviewing the history of a document, I want the ability to restore a previous revision, because I've made changes that I don't want to keep.

Design

The simplest would simply be a restore button when reviewing the revision.

Motivation

As an author, when I'm looking at the starred items folder, when creating a doc or folder there, I expect that those are also starred.

Acceptance Criteria

• Given the Doctoral UI with the starred pane open in the content sidebar
• when I create a doc or folder,
• then the doc or folder is created normally, and it is also starred by default,
• and I can see it in the sidebar.

The title search bar is implemented amidst the ContentList component. Factor this out into its own component to make it cleaner.

Motivation

When writing a documents sometimes I want to see previous content I had written, because I had written content there that I want to reference now or I want to see the change of a doc.

Design

Show a list of revisions on the right-hand side, maybe hidden by a button. Each revision should just be the date and time the revision was saved.

When editing, save a revision every 5 or 10 minutes and when the user navigates away from the doc.

Motivation

When the window gets narrow enough, the sidebar disappears to make room for the rest of the content, but I still need a way to get to my content and folders without widening the window.

Design

Have a toggle button that enables the content sidebar to reappear.

Acceptance Criteria.

• Given an open document,
• when I resize the window to be narrow enough so the sidebar disappears,
• then I observe a new button in place of the content sidebar.

• Given the doc open in a narrow window with no sidebar,
• when I press the new button
• then I observe the sidebar reappearing, floating over the document content, with the button still visible.

• Given the open doc with the floating sidebar,
• when I click the button again,
• then I see the sidebar disappear with the button in its original location.

Motivation

I need a way to identify the topics that I'm writing about and associate documents with those topics.

Design

1. Formal tag model where you can manage tags as a list.
2. Textual model where users can type in tags in the document context, e.g. #design

Motivation

I have lots of docs, but when I finish with them and won't be editing them again, I still want a way to store them and refer to them later, but out of the way.

Design

Have an archive tab and an operation, like a simple button, that archives a doc or folder (and its contents).

Motivation

At times, I want to restore the previous revision of a document as a new document, because I have previous content that I want to keep but without destroying the current doc I have written.

Design

Have another button when reviewing a revision that restores the revision to a new document.

Consider having the user enter a title for the new document at this time, or later, by titling the new doc with the title of the current doc + revision timestamp.

Navigate to the new document.

Motivation

When editing a doc, I'd like to know what folders the doc appears in and have the ability to move to those folders, since I use folders as an organizing mechanism for complex projects.

Design

Should be a fairly standard breadcrumb in the menu above the document. Organize it from left to right:

Home → Folder → Folder → Doc Title

Consider whether the doc title is needed.

When clicking on a crumb in the breadcrumb, navigate the sidebar to that folder.

Motivation

As an author self-deploying Doctoral, I want the ability to use the file system, instead of a running database, for storage, because I want to use a syncing service like Dropbox to manage backups, or I don't want the complexity of running such a database alongside the Express backend.

Design

Provide a way to switch to the file system when initializing the server and specify a path, either in a config file or in the command to launch the server.

Store the table of contents in a json file, contents.json, for now. Each document should have its own JSON file.

Acceptance

• Given the express server code,
• when I start the server and specify the folder to store my data
• and I start the front-end and create/edit documents
• then I observe the appropriate files (see Design above) in the folder I specified that contain the contents of my documents.

A/C

As a user, given a document with multiple textutal tags, when I save the document, then I see a list of tags in the document view.

Motivation

As an author, as I star documents and folders, I want to see a list of just them.

Design

Have a toggle in the sidebar to view regular contents or just the filtered starred docs and folders.

An author should still be able to navigate folders by clicking and searcn, and also open documents by clicking.

Motivation

As an author, I use the sidebar sorting features to help me organize and visually find documents and folders. I expect it to be consistent because it reduces the mental burden of having to reparse the sidebar if the sidebar sorting changes.

Acceptance Criteria

• Given I'm editing a document with the sidebar open with my sorting preferences selected in the sidebar
• when I refresh the browser tab
• then I see my sorting preferences in the sidebar are the same as they were before the refresh.

Motivation

As an author, when I'm working with several documents, sometimes I need to search for a doc while I'm writing. It's more convenient to be able to focus the search bar with a keyboard shortcut than using my mouse.

Design

• Press Cmd+/ or Ctrl+/ to focus the search bar.
• Press ESC or the same shortcut to refocus the editor.
• When the sidebar is collapsed, ensure it's shown with the keyboard shortcut, and also hides away again with the shortcuts that cancel.

Motivation

When managing projects with my documents, I want to be able to manage task lists so I can keep track of the progress of those projects.

Design

Enable the CKEditor feature in this doc

Motivation

While writing blog posts and reports, seeing the word and character counts helps me author for situations in which there are limits to those.

Design

Place the word and character counts in the menu bar on the upper right, or if there's no room, at the bottom of the header outline sidebar.

Motivation

When writing apps, I need to highlight text and format it as strikethrough, subscripts, superscripts, based on the needs of my document.

Design

Include the native features from the editor as buttons in the bubble toolbar.

Browsing the home page loads the app, which may read from the database needlessly.

The front page should be a static HTML page. The root of the app should redirect to the login screen or the dashboard.

Motivation

When I have many docs in a folder, I want a way to find the most relevant docs easily by scanning the list visually.

Sometimes, I need to see the docs I edited most recently, because I'm working with a few docs in the same place.

Other times, I have folders with docs that I'm organizing in a particular order, so I want to see them alphabetically by title.

Design

Add a small toolbar that can switch between the following options:

• sort by title
• sort by recentness
• sort ascending
• sort descending
• sort folders to top

Motivation

When reviewing the revision history of a document, I want to see the contents of a particular revision, so I can extract previous content, get a sense for the changes that have happened, etc.

Design

Click on a revision and see either read-only overlay of the content, or load the content into the editor in read-only fashion.

Indicate clearly that this is a previous revision with a notification, perhaps a yellow butter bar, similar to the warning bar when looking at a trashed doc.

A/C

As a document author, given I've tagged a bunch of documents, when I click on a tag in the tags list, I see a list of tags and a list of text snippets surrounding each instance of a tag in the list of documents.

Motivation

As an author navigating to a document via title search, when opening the doc, I expect the UI to be in a good editing state to reduce extra interaction.

Design + Acceptance Criteria

When the author is searching for a doc by title and clicks on the doc (or presses enter), the following should occur:

1. The sidebar should open the folder the doc is in.
2. The editor should be focused, so an author can start writing. (Currently, the focus remains on the search bar.)

For proper data models for the major objects in the app, instead of generic JavaScript objects.

Will require conversion to Firebase objects for the Firebase backend.

Motivation

As an author, when I'm writing in a narrow window with the headings outline collapsed, I still want to be able to navigate with the headings.

Design

Add another button like the one for the content sidebar. When clicking on a header, hide the outline again.

Acceptance Criteria

• Given a narrow window with the headings outline hidden,

• when I click on a button visible next to the content sidebar button,

• then I see the headings outline again.

• Given a narrow window with the headings outline exposed, where it would be hidden automatically,

• when I click on a heading,

• then the editor scrolls to that heading

• and the headings outline disappears.

Motivation

As an author, when I create a folder, I usually intend to name it something, so I would like the UI to enable me to specify a folder name when I create the folder with minimal effort.

Design + Acceptance

• Given the Doctoral sidebar
• when I create folder
• then I see the folder opened with the title highlighted at the top of the sidebar
• and I can type the new folder name and see it saved.

Motivation

I want to write with emoji and other symbols, but I don't have an app to do this for me. I may also have quirks in my typing that are hard for me to correct (e.g. "teh" when meaning to type "the"), and I'd like a way for the app to help correct it while I'm typing.

Design

Config panel somewhere for associating text input with the replacement.

Shortcuts for generated replacement text like dates and time.

A/C

As a document author, given a log, when I look at the sidebar, then I see a tag button in the filter bar.

As a document author, given I have added tags to several documents and saved them, when I click on the tag list button in the filter bar at the top of the sidebar, then I see a list of all the tags I've used in all the documents, each listed once.

Observed behavior

While writing, sometimes text you're just written will disappear. It seems to occur when a document is saved.

Desired behavior

This should never happen.

Reproduction

It's difficult to reproduce and happens nondeterministically. Generally, when you're writing, stopping for a second, then writing again, will eventually reproduce it.

Motivation

When my computer isn't connected to the Internet, I need a way to edit offline. Or I don't want to use a hosted service like Firebase, so I want to edit all of my docs locally.

Design

Need a way to pick the specify the deployment backend in code.

Or a setting to sync to a local destination while using a remote hosting service.

Motivation

I have lots of docs, so I need a way to call out specific ones that I'm working on, without having to use folder structure to do so.

Design

1. Tag a doc as a "favorite" (or similar term) by clicking a button.
2. Other?

Motivation

I want to ensure that my content is save, so I need ways to back up my docs and restore them if something goes wrong.

Design

1. Backups outside of the app itself, like downloading a zip file archive of all contents.
2. Use a database backup service.

Motivation

As a document author, I'd like to see the number of documents I've tagged with a given tag, so that I can understand the distribution of tags in my content.

A/C

Given I've tagged some documents, when I look at the list of tags, then I see the count of the number of docs tagged with each tag.

A/C

As a document author, given I've tagged a bunch of documents and have the tag list open in the sidebar, when I click on a tag, then I see a list of documents tagged with that particular tag.

Observed Behavior

When docs get large, the typing experience degrades with frustrating staccato-like delays.

As per ckeditor/ckeditor5-vue#42.

Desired Behavior.

Smooth typing.

Impact

Makes the app undesirable in general to use.

Possible Fixes

Don't use the Vue component and instead load the editor from a native build?

Observed Behavior

When headings have the same level (e.g. h2) and text, clicking in the outline on any of those headings will always scroll the editor to the first heading.

Desired Behavior

When clicking on the nth identical heading, the editor should scroll to the nth respective heading in the content.

Impact

This bug makes navigating with the headings outline difficult, as it's not terribly uncommon to have identical headers with the same text.

Potential Fix

Ensure that when clicking on each header, we know whether it's the nth header, then reference the nth in the content.

Motivation

As a user, I want to log into Doctoral using Microsoft authentication, because I prefer it to Google and other auth methods, or that's what my company uses.

Motivation

As an author, I have learned some standard keyboard shortcuts from other online editors that I would like to continue to use, to reduce the burden of adoption for Doctoral.

Design

Enable the following:

• Ctrl/Cmd+7 to create a numbered list.
• Ctrl/Cmd+8 to create a bulleted list.
• Ctrl/Cmd+Alt+1 for heading 1
• Ctrl/Cmd+Alt+2 for heading 2
• Ctrl/Cmd+Alt+3 for heading 3

If possible:

• Cmd+Backspace to delete from the cursor to the start of the same line.

Motivation

As an author, I want the ability to share a document publicly, because I want others to read the content easily and in multiple outlets other than my Doctoral deployment.

Design

Just a button to publish the current document's state will do for now.

Auto-generate a post URL from the document's title, from the same routine that generates the editable URL. e.g. /posts/myusername/document-title.html

The published state of a document will be called a "post."

The content of the post should not change when editing the doc after its publication.

Acceptance Criteria

• Given an editable document,
• when I click on the publish button,
• and I navigate to a URL based on my username and the document's title,
• then I see the contents of my document in my browser tab, but in non-editable form.

Motivation

While managing documents, I want to be able to move folders from one containing folder to another, in the process of organizing my content.

Design

Can be done with same tree dropdown as moving documents, with the trigger button placed in the sidebar.

• When users click on a button, a popup window appears with a tree-like structure of all available folders.
• When a user clicks on a folder, the current folder is moved to be contained by that folder.
• A user cannot move a folder to itself, to its existing containing folder, or any of its contained, child folders. Instead, such folders appear as disabled and nothing happens when a user clicks on them.
• When a user clicks on the same trigger button or a close button in the dropdown, the dropdown disappears.

Motivation

When managing trashed docs and folders, I want the ability to delete them permanently.

Design

In the Trash view, clicking on a button next to the entry will delete it forever.

For folders, show the number of items contained in the folder that will also be deleted.

For all entries, show the folder in which the entry was contained originally.

Since it's a sensitive, no-undo operation, add a level of safety and user-acknowledgement by requiring the user to click the delete-forever button twice.

Motivation

When writing apps, I need to justify text in particular ways for structural and clarity purposes.

Design

Include the native features from the editor as buttons in the bubble toolbar.

The Sidebar should be a layout-based component that is visible in the Dashboard and Document views and provide mechanisms to search and navigate.

The ContentList should be something more basic that accepts an array of Content objects to display plus flags of how to filter and sort them.

The Backend abstraction should have the semantics of the database, so Content and Document objects.

The Vuex store should carry the semantics of documents and folders. It should translate operations of the app into CRUD operations for the Backend adapters.