121 New TOC organization

[shaneataylor]

@infotexture Although there's more work to be done generally with the docs, I think this reorganization represents an MVP set of changes that moves us forward.

[infotexture]

👍 At first glance, this looks like a step in the right direction.

I'll pull the changes to build & test locally, then push to a staging server for further review.

In the meantime, are you able to update the feature branch and amend your commit with a signoff line per http://www.dita-ot.org/DCO ?

It's OK to force-push to your fork in this case: git push --force-with-lease yourfork.

[shaneataylor]

@infotexture Signed off. Thanks for reviewing & testing.

[infotexture]

@shaneataylor 🙇 Thanks, this looks like a much better overall structure that should help users to find what they're looking for more quickly.

There are still a few rough edges, but I think this will serve as a solid basis for further refinements. Detailed comments to follow…

[infotexture]

Several duplicate topics erroneously appear as children of the landing page.

Not sure if that's intentional.

[infotexture]

IMHO 👎 for the Release Notes archive, we have the Documentation versions menu for that.

Would also fill the PDF with extra pages and noise.

I've long considered removing the old Release Notes topics from the repo entirely, as they can be accessed via Git tags if they're ever needed.

— but I realize I may hold a minority position on this topic, so open for other opinions.

[stefan-jung]

• I'd suggest to merge Prerequisite software with Installing the DITA Open Toolkit. Currently it's a child, that does not make sense.
• I'd suggest to rename Extending the DITA Open Toolkit to Plugins, make it a top-level topic, explain there what a plugin is and then make the following topics child nodes of it:
  • Installing plug-ins
  • Removing plug-ins
  • Benefits of plug-ins
  • Plug-in descriptor file
  • Plug-in dependencies
  • Overview of plug-ins
  • Example plugin.xml file
• Customizing generated text should not be a top-level topic, but should be a child of Globalizing DITA content
• I'm not happy with the Reference section. This chapter contains the hot stuff, the content should be more popular. Arguments and options for the dita command and DITA-OT parameters should be top-level topics!

[infotexture]

"Next topic" links still reflect old hierarchy, but many such things may be coming from reltables and submaps that have not yet been updated, so this is to be expected.

[infotexture]

Installing plug-ins seems to need the context of the old parent Extending the DITA Open Toolkit, though this may be better combined per @xephon2's comments above.

[infotexture]

Building output has too many children. Parameters is better nested under Reference, and the output formats under DITA-OT transformations (though they appear there when viewing the page directly, so this may just be another map hierarchy glitch).

[robander]

IMHO 👎 for the Release Notes archive, we have the Documentation versions menu for that.
Would also fill the PDF with extra pages and noise.
I've long considered removing the old Release Notes topics from the repo entirely, as they can be accessed via Git tags if they're ever needed.
— but I realize I may hold a minority position on this topic, so open for other opinions.

I think I agree on not having the old versions, and definitely not having them in PDF. It's easy to find by switching versions on the landing page. I'm inclined to keep them in the repo because it means we still have them in the distribution, so people can find them -- I've used that before to more easily figure out when something shipped. Not sure if others have had that need, but I think it's fair to say a large number of DITA-OT users would not know to go look for Git tags if they wanted that info.

[infotexture]

Under Customizing HTML output:

• Customizing HTML with a .properties file appears twice
• 👍 for promoting Handling content outside the map directory
• Children of Setting parameters for custom HTML appear un-nested, alongside parent.

[stefan-jung]

@robander, I'd suggest to keep the old PDF notes in a static place and simply add them with

<topicref href="DITA-OT-1.8.5-ReleaseNotes.pdf" format="html" scope="external">
  <navtitle>1.8.x</navtitle>
  <shortdesc>DITA-OT 1.8.x Release Notes</shortdesc>
</topicref> 

So the user can access all notes the same way and does not have to care for their format.

[robander]

I did really like having Parameters at top level of TOC when it moved up back in 2.1 -- for me, it's the thing I look for more than anything in the docs, so having it move to the top level seemed like "Whoa, why didn't we do this ages ago". Yes, I realize I'm an outlier, but looking at current TOC I'm not sure I'd know where to find it, given that history.

[infotexture]

Under Customizing PDF output:

• Good idea to promote Generating revision bars — strictly speaking this does not require any toolkit customizations — just markup changes, but that distinction is likely irrelevant to users, so 👍
• The value of the History of the PDF transformation topic is debatable, per Drop "History of the PDF transformation" #167

[infotexture]

👍 for promoting Customizing generated text.

For related issues, see #31 & #165.

[infotexture]

@robander:

I did really like having Parameters at top level of TOC when it moved up back in 2.1

I recall similar feedback from @jelovirt, so this may be worth considering. I think the focus for the reorganization has been on the needs of first-time users and making things more approachable, but we shouldn't lose sight of veterans' needs entirely.

[infotexture]

Other customizations needs a bit more grouping, but the old Creating plug-ins topic was also a bit … diverse, so this is no surprise.

The old plugin overview topics are un-nested, & Customizing generated text was promoted, so shouldn't be here.

[infotexture]

Not sure about Verifying output as a top-level section w/ just one "Log files" child, but if there's more to come it may make sense.

I'd be fine leaving the "Log files" topic in Troubleshooting for now, and promote it later as suitable siblings emerge.

[infotexture]

So, that concludes my initial brain dump of feedback. Hoping others will chime in too.

For quick straw polls, adding 👍 / 👎 reactions to existing comments makes it easy to tally consensus.

[infotexture]

See #166 for additional thoughts on the re-organization of plugin-related content.

[infotexture]

I'll merge this to the feature/new-toc branch for further adjustments.