HTML docs: single page vs. chunks?

ForgeRock community logo

What size chunks do you prefer for HTML documentation?

  • An entire <book> as a single HTML file?
  • Split the book into one HTML file per <chapter>?
  • Even smaller chunks than chapters?

So far we have been generating one HTML file per <book>, because the docs are still mostly outline, little content. Even the OpenDJ Admin Guide is still only 112 pages in PDF. With a single book file, you can /search or Ctrl+F search to find what you want.

Trouble is, as the docs grow, pages can become quite large. What still works in a document with the equivalent of approx. 100 pages of text might not work so well in a document with the equivalent of 500 pages, plus a number of graphics.

Another alternative would be to generate both. Still discussing with the docbkx-tools community about that.

Advertisements

1 Comment

Filed under Docs

One response to “HTML docs: single page vs. chunks?

  1. I’ve updated the OpenDJ community site to provide both alternatives. See http://opendj.forgerock.org/docs.html.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s