Clarifying the documentation

[tscahill]

The attached PDF repeats this text, inline with the illustrations indicated.

Typically, programming and documentation don’t happen at the same time. As a result, these have a tendency to not reflect each other. In your project’s case, it is essential to get the vocabulary straight. For example: it is written: “Abookmark has two main pages: app page (bookmark manager) and nav page (bookmark bar).” However, [Fig 1] right-clicking on the extension icon doesn’t exactly reference that structure.
Some of the confusion arises from the text declaring there are two main pages, but the interface suggests there is only one. And actually the number perhaps should be 3.
I’m going to give a best guess at what is meant here, and where I get it wrong might be helpful. So, to get started, I’d re-write that sentence as:
“Abookmark has three primary user-interfaces (that clunker of a word combo can be replaced as it all becomes more clear):
the main app [Fig 2?] ( the bookmark manager), the topbar ? [Fig 3?] (A handy page to work the data within the structure built by the bookmark manager?), and the side panel [Fig 4, next page] ( to manage open and saved tabs).

[tscahill]

Untitled 1.pdf

[tscahill]

The text following page 1 in the pdf is just copy-pasted from the documentation online. I didn't proceed further with revision because my interpretation confidence was quite low.

[pfcao]

Thanks a lot. I've also read your another message.

I agree that current documents is not sufficient. I've received several feedbacks complainting it is hard to learn this app, and our uninstall rate is above 50%. We'll improve the documents and terminology gradually.

I think current app is a bit complicated to new users and I am removing some features from the general version.

[tscahill]

A simplification doesn't always require removal. While I'm still fumbling for the big, little and between picture of this project, I'm very confident that there is a integrated and coherent vision driving this emergent code. Synthesizing your understanding into bite-sized chunks that can be rearranged and interlinked into structured concepts easily grasped by those with absolutely no background relevant to using this product; that's a daunting sub-project, but perhaps the media itself can be the message (with thanks to Marshall McLuhan).

I mean, can the project also contain (or be!) its own documentation? Can that documentation be integrated into the functionality like a tutorial? I'm a little unclear about what can or cannot be included within an extension. If only we had a way to build in links to downloadable instructions. :)

[pfcao]

Thanks for all your messages. I will consider them carefully.

The codebase for this project is already quite large, so I doubt there will be any major new changes. I think the basic functions of this extension aren't very complicated: collecting and managing bookmarks, which isn't all that different from the native bookmark manager. While there are some other features, most are for specific tasks that new users don't need to worry about. For me, I use the nav page the most; I treat it like a new tab page. There's also the "store current tabs" keyboard shortcut, which can be used like OneTab. These are very simple features, and other extensions have similar functions; we just happens to use the bookmark system to achieve them.