Writing an INSTALL document for a library

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

Post Reply
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Writing an INSTALL document for a library

Post 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!
User avatar
feyd
Neighborhood Spidermoddy
Posts: 31559
Joined: Mon Mar 29, 2004 3:24 pm
Location: Bothell, Washington, USA

Post by feyd »

What about doing it in HTML and/or PDF?
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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?
User avatar
Luke
The Ninja Space Mod
Posts: 6424
Joined: Fri Aug 05, 2005 1:53 pm
Location: Paradise, CA

Post by Luke »

Please refer to documentation in /docs
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post by Ambush Commander »

Ah, that's such a cop-out! I've seen it, but personally I hate it when people do that.
nickvd
DevNet Resident
Posts: 1027
Joined: Thu Mar 10, 2005 5:27 pm
Location: Southern Ontario
Contact:

Post 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...
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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?
wei
Forum Contributor
Posts: 140
Joined: Wed Jul 12, 2006 12:18 am

Post 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
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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.
wei
Forum Contributor
Posts: 140
Joined: Wed Jul 12, 2006 12:18 am

Post 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.
User avatar
feyd
Neighborhood Spidermoddy
Posts: 31559
Joined: Mon Mar 29, 2004 3:24 pm
Location: Bothell, Washington, USA

Post 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.
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post 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.
Post Reply