Project Definition

OK, so we're going to work on a modern software development project. Nowadays that means its web-based and its pretty much going to want to work in the mobile space, although there are certainly projects which specifically target desktop, tablet, and/or mobile but not all three. Heck, if you're fortunate enough, you may even get to do some middleware and not have to worry about the cataclysm that is webapp UI design paradigm land. Lucky you!

In our case I have my own itch to scratch. I would like to be able to create some documents using a simple markup language, give each document a URL, and provide a reasonably decent, but simple, SPA front-end that can view them, allow me to authenticate myself and paste in new pages, etc. Now, I could utilize any of many wikis, but I have yet to find one that is simple, reliable, and has as few features as I actually want! I've used TWiki, XWiki, MediaWiki, etc, as well as various popular CMS systems in the past. They're all hard to configure, require separate database servers, are difficult to install, upgrade, etc. They have large attack surfaces, which requires you to keep updating too.

I don't want to have to setup and maintain a separate MySQL (or whatever) that I also have to backup, upgrade from time to time, and generally manage either. Ideally I'd like the whole setup to be simple enough that I can just zip it up and move it a machine somewhere, unzip, and start it up and have it work with nothing more than setting a pointer to Java somewhere, at most. Once I've built a document and finished it up, I can hand it off to people and they can use it offline through their browser.

I won't really go deeply into the genesis of these requirements. These documents will be 'book like' and as long as each section has a URL that I can build links to from other sections, it will do what I want. As far as a UI is concerned, the details will be worked out as part of our process, but I'd like to have some basic navigation features (breadcrumbs and a sidebar where I can place links to key sections). A full index and TOC can simply be sections in their own right with lots of links in them, they need not be special beyond having a sidebar type link that stays on screen for quick reference.

It would also be nice if the whole thing can be crawled and indexed. So, while an SPA is good from a UX perspective (IE it is snappy) the back end should also respond properly to the notional URLs which the application displays in SPA operation. Strictly speaking it doesn't even need to be an SPA, it just needs to be snappy and crawlable.

I want a responsive design which will produce a usable result on a desktop, tablet, or phone. Ideally the phone UX should be excellent, but it shouldn't detract from the utility of a larger screen. If this cannot be achieved in a single UI, then it would be OK if there's a separate SPA that has mobile URL and presents a variant interface. Such a mobile-only interface wouldn't need to be crawlable either.

So, we have a few user stories here:

1. displays content written in some sort of fairly simple markup.
2. allows definition of new content sections which get their own URLs and insertion of content into them.
3. user story 2 needs to be reasonably secure so only I can access it.
4. needs to be crawlable (IE each section needs a distinct URL)
5. simple high performance UI.
6. responsive for the whole range of screen sizes.
7. breadcrumbs
8. sidebar with links to specific sections
9. either no database or some sort of embedded database which can simply be packaged up along with the application as desired.
10. simple install/backup/reinstall on the order of 'move a zip file to a new place and unzip it'.
11. Ability to display any content section as raw markup so we can download it in source form. 
12. ability to upload image files as content sections and link to them as well.

OK, so that seems like both a small enough list of things to be doable, and large and complex enough to constitute a genuine engineering challenge worthy of some attention. I'd like to also keep in mind a couple of possible enhancements that might be useful in the future:

1. Some kind of in-place editor for our markup (right now we only need to be able to paste it in and save it, but being able to bring up an online editor is obviously potentially handy).
2. ability to version content sections so that older versions can be displayed if desired.
3. Some simply access control logic to allow for protected sections of content.

We don't have to implement these last 3 things, but lets keep them in the back of our minds as we come up with a design and implementation.