Page 1 of 1

Writing an INSTALL document for a library

Posted: Mon Jan 08, 2007 3:58 pm
by Ambush Commander
I understand this is slightly out of the realm of theory and design, but it's probably quite important, and does have ramifications coding side.

In light of some new convenience features I added to my library's API, I've decided to revamp my installation document. The original was organized like this:

1. Compatibility
2. Including Library
3. Setting up your application
4. Configuration
5. API use
6. Quick install

While I was rewriting, though, I realized that I was trying to simultaneously cater to three groups of users: advanced users who already knew about all the issues and just needed some quick API information and mention of caveats, beginning users who needed to be educated about the subtleties of character encoding and standards compliance, and impatient users who wanted the library working fast as possible.

With so many people, it's easy to see when one section might be helpful to one group but an annoyance to another. I'm not exactly sure how to go about fixing this, though. Split it into an INSTALL-advanced, INSTALL-comprehensive and INSTALL-fast? So wordy and non-standard!

Posted: Mon Jan 08, 2007 5:38 pm
by feyd
What about doing it in HTML and/or PDF?

Posted: Mon Jan 08, 2007 6:49 pm
by Ambush Commander
That's a possibility, although it makes it a bit more bulky (a browser has to be fired up to read the doc). It's a good idea though, but it then leads to another question: what goes in the INSTALL file?

Posted: Mon Jan 08, 2007 6:51 pm
by Luke
Please refer to documentation in /docs

Posted: Mon Jan 08, 2007 6:53 pm
by Ambush Commander
Ah, that's such a cop-out! I've seen it, but personally I hate it when people do that.

Posted: Mon Jan 08, 2007 6:55 pm
by nickvd
INSTALL will be the quick install, just the basics to get working with the lib.

Then, as feyd suggested, create a simple, yet attractive documentation html file(s) (see http://www.codeigniter.com/user_guide for an example of some of the best documentation i've seen for a framework) that will contain the three different sections.

Of course you will add the "for more info see....." in the INSTALL/README file...

Posted: Mon Jan 08, 2007 6:59 pm
by Ambush Commander
The plan of attack is an INSTALL file with impatient instructions that briefly mention the caveats, and then more fully-fledged HTML documents in the docs/ directory. Works for me.

Perhaps I should learn docbook?

Posted: Mon Jan 08, 2007 7:03 pm
by wei
INSTALL is just that, how to INSTALL your software, everything else is reference to the documentation.

could be just a simple as,

"unzip, upload, read the docs." no examples either, unless is an installation example.

you could also explain the directory/file structure, e.g. docs contains the documentation, etc.

also, you can write it in one of those nice markups such as "Textile" or "MarkDown", so it read easily as Text or transformed into HTML/PDF

Posted: Mon Jan 08, 2007 8:25 pm
by Ambush Commander
I'm not so fond of either of them, having tried them out. They're great for simple stuff, but go into anything complex and you'll have troubles. LaTeX is a bit out there in terms of semantic data, I'd rather keep with an XML-based format, i.e. pure XHTML or DocBook.

Also, I'd like my install document to be:

1. Useful
2. Concise
3. Comprehensive

Which may cause difficulties.

Posted: Mon Jan 08, 2007 11:55 pm
by wei
Latex is great for writing scientific papers with maths, it excels at defining math notations, but lacks completeness in layout (unless you willing to spent lots of time writing the styles). I find it horrible at doing code samples, and it table structure are pretty dismal.

no clue how docbook feels, seems very verbose and time consuming to edit without a nice non-xml view editor.

Posted: Tue Jan 09, 2007 12:29 am
by feyd
Have you looked at Doxygen? Current builds support rendering chunks of LaTeX; incorporating images; different languages; output to HTML, PDF, RTF. (I think even man pages..)

As for the INSTALL file itself, I'd agree with wei and nickvd. It should be a simple basic quick set up. You can easily refer to the more in-depth documentation if users need more information or explanation. I would probably preface the INSTALL with some text about who the INSTALL is intended for and that computer newbs should probably use the more in-depth documentation.

Posted: Tue Jan 09, 2007 6:28 am
by Maugrim_The_Reaper
Docbook is fairly simple to write with - the idea is to use a minimum level of tags possible otherwise you could spend weeks learning everything in the standard. The Zend Framework manual is written in Docbook, worth checking out to see how it's laid out, setup in svn, and can quickly generate HTML under Linux or Cygwin. Layout for a minimal Docbook document is fairly basic but functional, a good CSS2 style would help it along if required.