[OPEN-ILS-DOCUMENTATION] DIG AsciiDoc formatting questions

[Dan Scott]

On Mon, Mar 25, 2013 at 11:35:59AM -0400, Yamil Suarez wrote:
> Hello everyone,
> 
> I am working on some updated official documentation, but before I
> submit it I wanted to ask some formatting questions on the list to
> preserve the answers for posterity.
> 
> Question 1: I remember hearing a while back that when we are finally
> including AsciiDoc documentation into the code/documentation Git
> repository we should limit the line widths to something like 72
> characters. Is this correct at all?

Commit messages should be no more than around 72 characters wide, as
various tools (like "git log") expect email-like formatting and look
very strange with long lines.

For the docs themselves, I've been working on keeping lines around 80
characters wide or less. Rationale being that if you run "git diff" to
compare a previous version to a newer version of a given file, it's a
lot easier to spot a one-character difference in the middle of 80
characters than it is in the middle of 320 characters :)

But in the end: whatever keeps the actual content of the docs marching
forward is what's best. Don't let rules of thumb get in the way of
writing & updating docs.
 
> Question 2: I have worked on updating some TPAC introduction
> documentation. The EG 1.6 version of the documentation was broken up
> into multiple files, i.e basic_search.xml and advanced_search.xml.
> Should the updated version for EG 2.4 be also broken up into
> multiple files, or should I make them a large single file?

If the basic search help might be used in multiple locations, and
separately from the advanced search help (for example, for a link from
the TPAC that points to a basic search help page vs. a link from the
advanced search interface that would link to the advanced search help
page), then separate files would make sense. Otherwise, it doesn't
really matter.

Thanks for working on the docs!