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! _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
