A very specific kind of outliner

Background

A few times last summer, I discussed my attempt to convert a school Policy Manual from a collection of ~140 PDF files into a single wiki. (The most thorough discussion was at #13430, and it links to the others.) I put that aside but recently came back to it. The reason for the delay was that I was really not sure enough about an outline editing interface for TW novices. I’m trying to address that now, and I’m hoping this group can give me some feedback.

I plan on doing the initial conversion of the files myself, but then I want to turn it over to someone else. I’m assuming that someone would be the Superintendent’s administrative assistant. She has no experience with TiddlyWiki (I assume – I’ve never asked.) So I’m trying to create an editor that would be intuitive enough that I could show it to her in an hour or so and she could be working with it right away.

Request

If you’d be willing to try it out – mostly editing existing Policy documents to see if this is useful, I would appreciate it. It’s live at https://crosseye.github.io/rham-policy/0.7.3/. The first three sections of documents (1000’s, 2000’s, and 3000’s) have been converted; most of the rest are just placeholders. I assume I don’t have to tell you that you won’t harm anything by making changes, saving locally, whatever.

If you open one of these documents, you will see a new view toolbar icon, image 1, that will launch you into my edit mode. Poke around, see how it goes. I’ve spent no time worrying about initial document creation yet. If I can’t get editing existing documents right, I have no hope of that.

Note that this also includes some enablement for a workflow. Documents are not edited willy-nilly. The flow is dictated by our Board’s bylaws, and proposed changes are made generally by our lawyers or the Superintendent, at the Board’s direction. But then they go to the Policy Committee for review, which might introduce further changes. After that, the whole Board discusses them at one meeting, and again might introduce changes, and then votes on them at a subsequent meeting. If there are serious concerns at any level, the process might restart at any step. So the tool allows for a current document and a number of named draft versions, which might branch off one another at different points. Eventually the draft is approved, and there’s a “Promote” button here to archive the current version and make the draft the new version. (Archived versions are just stored in CompoundTiddlers; there’s not yet any mechanism to unarchive them.)

But the main point here is to be able to edit whichever version. So the editor follows the hierarchy defined in the Policy and presents it as editable sections. That’s mostly what I hope you’ll be able to test. Does it work? Is it reasonably intuitive? What suggestions do you have for enhancing it? (Please note the two tabs, Preview shows you a rough rendering of the final document, letting you edit one section at a time. Structure shows you just the hierarchy, still letting you edit sections, but also move things around.

I have also started separating out the workflow and outline handling into a reusable plugin; while it’s going reasonably well, I’m a little stuck and wondering if it’s worth pursuing. So I’d like to know if this is something you imagine ever wanting to reuse?

Wiki design

I have a few design goals for this wiki: most of them familiar to TW users. I want to consolidate this information into a sharable document. I want every policy to have a clear, permanent home. (Right now you have to navigate through an obnoxious SharpSchools-powered early 2000’s paginated web interface to even find the right PDF.) But more than that, I want even small subsections to have their own URLs, so that I can point to, for instance, Policy1410(C)(3). That also involves my obsession with clean URLs.

Note that I am trying to keep the document looking as much like the existing PDFs as possible in a web interface. If this Policy uses I. Roman / II. Numeral / III. Headings, and that one A. Just / B. Uses / C. Letters, and a third one has ALL UPPER CASE TITLES, I want to support them all. That leads to a fair bit of complexity.

The actual tiddler structure is explained in detail in the link above. But briefly, each section in an outline is its own tiddler. It has a display-style property which describes how it lays out its children (inline, bullets, headers, etc.) The parent-child relationship are carried only in the title structure: Policy1410(something) is a direct child of Policy1410 and its children all look like Policy1410(something)(next-level), and so on.

This is not really a wiki. There will only ever be two or three editors at most. The content won’t be edited much more than monthly, usually not even that often. Many policies will remain static for many years.

Instead, it is a use of TW for some of its other features: the easily-sharable single file design, the ability for Policy Committee members to take their own copies and make suggested edits, the searchability (entirely missing from the static PDF version), etc.

Thank you

Thank you for any feedback you can offer, at any level. This has been a one-man show, and I really would love to hear what others think, even if it’s just, “What, are you crazy? That’s a stupid idea!” :slight_smile:





1And if you know of a good icon for a (document) outline, please let me know. Searching for it is hard, because there are few good synonyms for “outline” in this sense, but it’s used in the silhouette sense all the time when discussing icons. Or if anyone has a better design, I’d appreciate hearing about it…

Ok, at least one thing was easy enough to fix. This still isn’t wonderful, but it will do for now:

outline-button

If this is intended for a general audience, it would be better to use a more widely adopted technology, such as Markdown. Using Markdown also makes it easier to integrate with version control tools.

It seems TiddlyWiki is intended to handle the interactive components. This is indeed one of TiddlyWiki’s strengths.

Using TiddlyWiki as an indexing tool for PDFs also appears to be something it excels at.

It looks like the branches cannot be edited; only the leaves have that editing capability. The “Add Section” button does not respond. I’m not very familiar with the workflow, so I don’t fully understand the purpose of the various buttons. It appears to be a solution tailored to a specific enterprise and lacks value for broader adoption.

It might be a good idea to use Markdown syntax for the editing rather than wikitext, so long as macros such as my <<sections>> and <<cgs ... >> still work… I’ll think about it. If you’re suggesting, though, something like one of note-taking or documentation tools that work with multiple Markdown files, that won’t work for my use-case. I really want the single-file deployment.

It’s more about the fact that this is single-file, but still quite dynamic.

Well, I’m able to edit pretty much any section, so I’m not sure what you mean.

Oops, wonder when that broke!

I suspect you’re right. It’s useful only if all of these are true:

  • You have formatted outlines to maintain
  • The outlines have radically different structures
  • You want each part—large, medium, or small—to be addressable

I don’t think the audience is very large. It’s just not clear to me whether it’s just an audience of one!

Thanks for the feedback!

Have you considered developing this software based on Kookma’s section plugin?

The kookma plugin automatically generates heading styles like “1.1.1”.

It seems the heading styles in your app cannot be changed. Doing so will result in an error.

Since there is no user manual, I can only figure out how to use it by trial and error. I gave it another try, and now I have a better idea of how the app works.

The Tiddlers created after clicking “Add Section” are given random names, making it difficult to find the specific Tiddler you’re looking for.

polycy-nbr was not generated automatically.

I don’t know how to add a section under “Overview.”

I don’t know how those policies ended up listed under that section either.

If there is a blank space in the title, it generates multiple tags in children.

I don’t know how to add a preview to Tiddler.

On my end, only the leaves show the outline icon. The branches do not show the outline icon.
->So far, I’ve noticed that if there is a “Policy” tab, an outline icon appears, and you can edit it.

The “Add Section” feature only works in the ‘Structure’ tab. It doesn’t seem to have any effect in the “Preview” tab.

This outline editing feature appears to be designed for general users. The “Draft” feature also seems intended for general users. However, strings like “Return to Policy” and “Add Legal Reference” do not appear to be intended for general users.