Page MenuHomePhabricator

Increase user control over document hierarchy in Phriction
Open, Needs TriagePublic

Assigned To
Authored By
Jun 15 2015, 5:53 PM
Referenced Files
F1754779: Screen Shot 2016-08-08 at 9.24.42 AM.png
Aug 8 2016, 5:33 PM
F1754722: change.png
Aug 8 2016, 4:43 PM
F1754720: Screen Shot 2016-08-08 at 9.38.48 AM.png
Aug 8 2016, 4:43 PM
F1754704: Screen Shot 2016-08-08 at 9.23.36 AM.png
Aug 8 2016, 4:31 PM
F1754706: Screen Shot 2016-08-08 at 9.24.42 AM.png
Aug 8 2016, 4:31 PM
"Like" token, awarded by kuba-orlik."Like" token, awarded by am9obgo."Party Time" token, awarded by spawnlt."Like" token, awarded by SvHu.


Control over the hierarchy in Phriction would be awesome; as more and more of our docs are moving there, it's becoming impossible to find anything while browsing, and the search is not super-helpful.

When I say "control", I mean any (or all!) of the following -- happy to explain why I think they're important, or anything else, in more detail in email or person:

On the auto-generated hierarchy at the bottom of any page with sub-pages:

  • ability to change number of levels shown (statically, as an option when editing the page)
  • in a crazy perfect world, ability to hide/expand sublevels when viewing the page
  • ability to visually tag pages in some way, so it's easier to categorize pages while skimming down the long list

On the auto-generated table of contents on the upper right of each page:

  • ability to move the table of contents -- even just one more option (putting it at the top of the page, as part of the page, rather than part of the sidebar) would make it much easier to navigate some pages
  • ability to change number of levels shown (statically, as an option when editing the page)

Event Timeline

angie raised the priority of this task from to Needs Triage.
angie updated the task description. (Show Details)
angie added a project: Restricted Project.
angie added subscribers: angie, jhurwitz.

I think these kinds of changes are generally things we're aligned with pursuing.

Some other changes we're thinking about in this vein are:

  • Letting users define navigation for a section of the wiki (maybe a left-hand navigation sidebar, or persistent tabs). This would probably be something like taking all the sibling pages at some level and putting them on all the sub-pages, as related categories. For example, the "Employee Guide" section could automatically link to "Logging Vacation Time", "Updating Tax Information", "Policy Handbook", "Corporate Mission", etc., in a persistent nav on every page in the section.
  • Giving users some degree of control over personalizing or distinguishing sections of the wiki (maybe adding images or header colors, possibly some level of light theming).

Your stuff is all pretty reasonable. These ideas are a little more out there so I think they're less likely to all make the cut, but changes in that vein and with a slightly larger, more Wiki+CMS-ey scope are what we're currently looking at, if those ideas or other similar ideas resonate with you.

I'll mention a couple technical things here, too:

  • I'd like to look at splitting "Edit Content" from "Edit Other Stuff Which Is Not Content", so we can stuff the latter full of controls without making content editing more tedious or cumbersome.
  • I also think improving human-language diffs (discussion in T3353) would be a huge quality-of-life improvement in the wiki. This has a straightforward implementation plan and only moderate technical difficulty.
  • It would be nice to have a 2-up preview in "Edit Content" (some discussion in T3967). I think this is technically quite feasible, it's just a bit involved to get scrolling working well for large documents.

[angie initially submitted this for me because I didn't have an account, but I'm the original requestor]

Glad to hear this is aligned with your plan :-) I do think our org has a much larger problem with finding docs and navigating than we do with content editing in Phriction. Some specific responses:

  • Defining a persistent navigation for a section would be a big help! Again, it would be great to get some control over how deep it goes/whether it shows up (for example, being able to choose whether the children of sibling pages show up). I also think this would be less helpful to navigation problems than ability to control the auto-generated hierarchies at the bottom of the page -- in fact, I think in some ways it's included; the request for controlling number of levels shown goes up to sibling and parent pages as well as down to multiple levels of children. (Having the directions broken out into different places would really help legibility/discoverability, though, of course.)
  • Visual distinctions between sections would again be awesome, but I think not as much of a boost as a better navigation.
  • I definitely agree that this level of pickiness on navigational stuff (and other skinning) is irrelevant to most content editors, and having it in a separate panel makes a lot of sense.
  • I don't mind the diffs in Phriction at all; I actually think they're pretty good, compared to other platforms I've used.

Is it currently possible to configure number of levels to be displayed for wiki document hierarchy in Phriction? The current default seems to be equal to '2'. I have seen D8061: Show configurable level in the Document Hierarchy in Phriction., which is not resolved. Perhaps, I have missed other relevant info.

Some sketches in M1466, but essentially we'll give you some default options, and a "navigation builder" which you can select on a per-page basis. Based on the mocks, the "hierarchy" moves to being a side navigation, and defaults now to one level. From that you can "Manage Page" and change the default for that page. Rough thinking is:

  • Hierarchical, 1 Level, Alphabetical
  • Hierarchical, 2 Levels, Alphabetical
  • Hierarchical, 1 Level, Chronological
  • Hierarchical, 2 Levels, Chronological
  • Saved Custom Navigation
  • New Custom Nagivation

Like Projects, you'll be able to build whatever menu you want. We'll start with three items. "Label", "Link", and "Spacer". You'll be able to re-order the menu as you please. Save it to just one page, or apply it to multiple pages.

The shortest path on the nav is probably something slightly more directly porting Profile Menu editing:

Screen Shot 2016-08-08 at 9.23.36 AM.png (905×1 px, 166 KB)

...except in Phriction chrome, and that "Add a new thing" menu will contextually include "Phriction Hierarchy" as an element type. The default menu will just be one "Phriction Hierarchy" element, instead of several different elements (Profile, Workboard, etc). If you include an element of that type, you'll have options to customize it within the element detail screen, similar to how you can customize links:

Screen Shot 2016-08-08 at 9.24.42 AM.png (873×1 px, 117 KB)

...except that instead of those options, you'll have options like "Order", "Display Levels", "Always Show Hierarchy Relative to Original Page", and "Limit" (or whatever we dig up reasonable use cases for here and in connected tasks).

This single menu item generates a lot of different clickable links in the menu, but it's all "one item" from the perspective of editing.

If you want something totally custom (arbitrary order, labels in the middle of the list, some weird selection rule for what makes the cut), you don't add a "Phriction Hierarchy" element and just add a bunch of "Link" elements instead, and can have complete control over the menu (including linking off-site, to other applications, to projects or repositories, etc) at the cost of needing to do a little more legwork upfront.

This also lets you have several custom links, a picture of a cat, a divider, then a hierarchy if you want.

I think both are about 95% equivalent, my version ("a Hierarchy is a single menu item") is just easier for me to do from an engineering viewpoint and the other version I'd have to think about for a while before I could even guess how much work it is. I think the simpler-to-implement version is a bit more flexible/powerful too, although maybe not quite as intuitive at first glance.

My intent was to basically port over a customizeable nav list like we already use in AphrontNav everywhere, label, item, spacer, and have that basically editable and re-usable. I want to take a pass at something similar for /home/ so we're looking at all the use cases before building anything.

So just to understand your point, instead of having pre-selectable layouts, we ship just 1 level by default and anything else is custom?

Yeah -- the specific change I'd expect is basically that this:

Screen Shot 2016-08-08 at 9.38.48 AM.png (675×935 px, 85 KB)

...becomes this:

change.png (675×935 px, 37 KB)

...where red is removed and green is added, except that I accidentally turned my new menu item red when it should be green and literally can't figure out how to fix it.

When you click "Edit" on that "Automatic Hierarchy", you get the ordering/levels/etc options. You can also remove the element completely if you want a full custom menu (or you can add 3 of them if you're CRAZY~).

I'll also try to make your design look as nice as mine but no promises!

Can I select which page I pull my hierarchy from? I think that works for cases where you want the navigation to be persistent among the children, to just always pull from parent hierarchy.

I'm hoping to get away with two options, e.g. a checkbox like this:

  • Always Show Hierarchy Relative to <Original Page>

...which you can check to lock the hierarchy to display relative to the page where the menu is defined. If you don't check it, the hierarchy is relative to the current page.

(I'm hoping there's no real use case for "show some other arbitrary page's navigation", although who knows.)

When you click the pencil icon next to the "Hierarchy" item, you get to a page like this one:

Screen Shot 2016-08-08 at 9.24.42 AM.png (873×1 px, 117 KB)

Instead of having the options Name, URI and Icon, it has the options Order, Levels, Limit, and Relative instead (or as few as we can actually get away with building):

Order: [ Alphabetical ]
Levels: [ Show 2 Levels of Hierarchy ]
Limit: [ Show 20 Pages ]
Relative: [ ] Show Hierarchy Relative to <Original Page>

Why is Phriction being kept on such a low priority? This task has been since 2014 if we take into account this: T5254: Allow top-level wiki doc to display entire document hierarchy instead of only 2 levels

In T8552#233072, @mejaz wrote:

Why is Phriction being kept on such a low priority? This task has been since 2014 if we take into account this: T5254: Allow top-level wiki doc to display entire document hierarchy instead of only 2 levels

As with most projects; It's a matter of having limited resources. I think most paying customers don't really care about the wiki (which is just a guess. I'm not affiliated with Phacility). Personally I love Phabricator but also don't really care about the wiki in Phabricator. Our technical documentation is done in asciidoc in a GIT repo. Makes it easier to develop documentation alongside features since the documentation can live in a diff / branch. Since the rest of the company is in a "normal" wiki (XWiki) all of our IT related stuff (non product documentation) goes there as well. We only use the Phabricator wiki as a glorified release note editor atm. Al tough I won't rule out we will make an XWiki plugin which integrates Phabricator a bit better (hoover over T's and D's and such) and move away from Phabricator's wiki entirely.