Where does documentation go?
Moderator: General Moderators
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
Where does documentation go?
You know, end user documentation for developers who are using a library. Should it get packaged with the library itself, or should it be kept on the library's website? Maybe the install documents should get packaged, but everything else stays on the website?
What do you do?
What do you do?
- Kieran Huggins
- DevNet Master
- Posts: 3635
- Joined: Wed Dec 06, 2006 4:14 pm
- Location: Toronto, Canada
- Contact:
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
- Kieran Huggins
- DevNet Master
- Posts: 3635
- Joined: Wed Dec 06, 2006 4:14 pm
- Location: Toronto, Canada
- Contact:
If you really want to spend the time, follow the PHP manual format - it's quite good.
I also like the visual jQuery documentation: http://www.visualjquery.com/1.1.1.html
Basically, a list of your API's interfaces and how to use them. Examples are nice, but anything more should stay in the wiki.
Definitely, definitely include a link to the online docs / wiki!
I also like the visual jQuery documentation: http://www.visualjquery.com/1.1.1.html
Basically, a list of your API's interfaces and how to use them. Examples are nice, but anything more should stay in the wiki.
Definitely, definitely include a link to the online docs / wiki!
- Chris Corbyn
- Breakbeat Nuttzer
- Posts: 13098
- Joined: Wed Mar 24, 2004 7:57 am
- Location: Melbourne, Australia
I currently use PhpDoc so I've got (up-to-date) comments in my code to generate API documentation from. At the time I package up for a release I generate some docs for the code base and add them to the doc/ directory (which is just an empty folder in svn). I like to also keep a separate online manual though so I can easily add code examples and tutorials where I see fit. I'm moving everything over to DokuWiki at present.
Usually I'm just happy with API documentation providing I can find at least one page on the website which has some example code.
Usually I'm just happy with API documentation providing I can find at least one page on the website which has some example code.
- RobertGonzalez
- Site Administrator
- Posts: 14293
- Joined: Tue Sep 09, 2003 6:04 pm
- Location: Fremont, CA, USA
I'm really starting to dig phpDoc. It makes setting up a documentation base very easy. And it gives you some perspective on code commenting. My first go round made my comments look like a broken chain wrapped around a spinning axle. It wasn't pretty.
You could always maintain a central documentation area on your site, then include a single README doc in the distribution that states something to the effect of 'For detailed documentation, refer to http://www.mysite.com'.
You could always maintain a central documentation area on your site, then include a single README doc in the distribution that states something to the effect of 'For detailed documentation, refer to http://www.mysite.com'.
- CoderGoblin
- DevNet Resident
- Posts: 1425
- Joined: Tue Mar 16, 2004 10:03 am
- Location: Aachen, Germany
I also use PhpDoc with the results in a separate area. This enables me to re-use the same code and have a common documentation area for those things I reuse for multiple projects. I know some people find Test Driven Development an advantage for figuring out how things work. They look at the tests to see how things work.
- Maugrim_The_Reaper
- DevNet Master
- Posts: 2704
- Joined: Tue Nov 02, 2004 5:43 am
- Location: Ireland
API is secondary documentation IMO - it helps when trying to locate a specific method or property or perhaps when subclassing etc - its usage differs quite a bit which is why its popular. Long text documentation is primary since it's there you expect to find the example/tutorial type bits that are needed to get started along with documenting of userland use. Releasing unit tests with the source code is also helpful - I'm willing to grab them from subversion/cvs separately but part of the point of unit tests is to let other developers quickly ascertain the integrity of a library with minimal effort - I have my test setup. Unit tests are also good documentation though in a more developer-focused way.Basically, a list of your API's interfaces and how to use them. Examples are nice, but anything more should stay in the wiki.
I prefer if documentation is bundled with a release since it does help to have offline documentation for reference. It even helps when you are stuck on a 56k connection and it's a particularly slow evening on the internet. So I would advise including it - not just leaving it online, or offering some type of doc download option if possible.
I suppose this is also why I typically refer to a Wiki as a temporary medium (unless its primarily the backbone of a purely online documentation site). Wikis make for good online documentation but bad offline documentation. Plain HTML or Docbook is a lot better, and if you really need the wiki than try locating a Wiki markup translator. Final documentation for a library (my humble opinion) should be maintained in a portable format like HTML or Docbook XML where possible. Leaving it to the mercy of wiki markup pretty much forces you onto the online only path unless you have a wiki capable of making PDF exports.
Since I rambled on about this I do tend to a lot of work offline - so unless the library is easy to follow or very familiar, if it lacks bundled documentation I'm less willing to use it.
Heh, I've meandered this far... Personally I write everything in Docbook XML using the XMLmind editor. After that for any of my applications/libs I have a cron task which can export the Docbook and compile it into HTML on a regular basis and copy it all to an intranet location at work. This way the documentation publication is automated as much as possible. I use XMLmind since hand editing Docbook is a little too error prone. One mistake and the lint errors will drive me up the wall...
- jyhm
- Forum Contributor
- Posts: 228
- Joined: Tue Dec 19, 2006 10:08 pm
- Location: Connecticut, USA
- Contact:
Feel free to ignore this as every technical documentation writer seems to or does, but line width!! It is very hard to read extensive technical literature when the line width is so long that your eye looses it's place on the next line (and man do I HATE horizontal scrolling! If I wanted to watch a tennis match I would go to one!). A decent rule is to make sure the line is long enough to hold a complete thought, with out breaking up phrases that naturally go together ( that would also create confusion) but read a line to the end and just before the start of the next line goes out of your periphial, mark that as the end point for your paragraphs.
P.S. When my posts get longer than one paragraph I tend to throw in line breaks as we don't have paragraph controls on the post forms.
P.S. When my posts get longer than one paragraph I tend to throw in line breaks as we don't have paragraph controls on the post forms.
- Kieran Huggins
- DevNet Master
- Posts: 3635
- Joined: Wed Dec 06, 2006 4:14 pm
- Location: Toronto, Canada
- Contact:
- jyhm
- Forum Contributor
- Posts: 228
- Joined: Tue Dec 19, 2006 10:08 pm
- Location: Connecticut, USA
- Contact:
I'm with your gf. Seems only Graphic Designers are up on this. Typography goes back centuries to the first mass produced Bible and the Annals of Marco Polo. The main job of the typographer is a humble one, to produce legibility and readabilty to her 'end user'.Kieran Huggins wrote:Somewhere between 40-60 characters is considered "optimal" line length for reading... according to my graphic designer gf.
Not that 'techies' really care about typography, but I try and encourage these princibles in hopes that it will catch on. I get eye fatique easy and if a book is printed with a type face witch hurts my eyes, I refuse to read it. Ironically I took a graphic design course in which one of the required text books was written in a mono-spaced aka type writter fonT.
A really great starting reference is a small book, really a pamphlet, calledThe Mac is not a Typewriter. Despite the title it is a good start for anyone. The same author has good follow up books. Although not the de facto reference of the snobbiest of type snobbies, a good primer for making your copy more easy on the eye.
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
We're talking about end-user documentation as in tutorials, quick-starts, etc. I already provide Doxygen and PHPDoc generated API documentation. I currently do not package API docs with the library.
Unit tests are currently packaged with the library, despite their uselessness to the average user. It's very simple to separate the "real" HTML Purifier code though. I agree unit tests are valuable documentation, but they're also heavy-weight.
My current situation is that I have a bunch of very bare-bones HTML files inside my distribution. These range from developer notes to fully fledged end-user tutorials. Because they're packaged with the library, I have to keep them "light": this means no JavaScript, no images, minimal cross-linking. Which is a bummer.
I mostly share Maugrim's view on wikis: they're good for temporary docs, but tend to be a little scatterbrained unless you really want to devote a lot of time to creating good naming conventions, etc. They're also difficult to export for offline reading, although it's not impossible.
jyhm, it's good of you to bring up typography as an important element. I dabble in LaTeX, so I do have a general idea what good typography is and what it isn't. However, my philosophy regarding line widths is: don't fret! As long as a user can resize the browser window to make your lines wider or thinner, you're gold. Browsers don't have a TeX-style hyphenation system or a really good column format, so I'd worry about that sort of stuff if I was doing a PDF release (it always kills me when people just print straight out from a web page to a PDF: PDF's are capable of so much more! Use a legit typesetting system!) But... that's not really on topic.
So... back on topic...
I think the general consensus is that the bulk of your documentation can be reasonably be made available online-only, but as Maugrim points out, be sure to offer a way to download it. I think this a good compromise.
A few questions:
Unit tests are currently packaged with the library, despite their uselessness to the average user. It's very simple to separate the "real" HTML Purifier code though. I agree unit tests are valuable documentation, but they're also heavy-weight.
My current situation is that I have a bunch of very bare-bones HTML files inside my distribution. These range from developer notes to fully fledged end-user tutorials. Because they're packaged with the library, I have to keep them "light": this means no JavaScript, no images, minimal cross-linking. Which is a bummer.
I mostly share Maugrim's view on wikis: they're good for temporary docs, but tend to be a little scatterbrained unless you really want to devote a lot of time to creating good naming conventions, etc. They're also difficult to export for offline reading, although it's not impossible.
jyhm, it's good of you to bring up typography as an important element. I dabble in LaTeX, so I do have a general idea what good typography is and what it isn't. However, my philosophy regarding line widths is: don't fret! As long as a user can resize the browser window to make your lines wider or thinner, you're gold. Browsers don't have a TeX-style hyphenation system or a really good column format, so I'd worry about that sort of stuff if I was doing a PDF release (it always kills me when people just print straight out from a web page to a PDF: PDF's are capable of so much more! Use a legit typesetting system!) But... that's not really on topic.
So... back on topic...
I think the general consensus is that the bulk of your documentation can be reasonably be made available online-only, but as Maugrim points out, be sure to offer a way to download it. I think this a good compromise.
A few questions:
- Should the auto-generated API documentation be made downloadable?
- Should there be tasteful graphics in tutorial-style documentation? A few pictures can really spruce up a document, at the cost of a few more seconds of download time (I love how A List Apart has an opening graphic for all its articles).
- How important is a PDF download to you?
- Is the pain of compiling docbook worth it? (I currently use HTML)
- jyhm
- Forum Contributor
- Posts: 228
- Joined: Tue Dec 19, 2006 10:08 pm
- Location: Connecticut, USA
- Contact:
I can't answer your all your questions AC. But I can put my two bits in for PDF. If you can and have the time go for it. I love it when there is a good PDF copy. Recently I printed out the GENTOO manual because I did not to want to refer to the screen all the time.
All those items in your items in your list I think are useful when ever they add to the users experience. I'm Short on words but I commend your attitude AC.
All those items in your items in your list I think are useful when ever they add to the users experience. I'm Short on words but I commend your attitude AC.
- Maugrim_The_Reaper
- DevNet Master
- Posts: 2704
- Joined: Tue Nov 02, 2004 5:43 am
- Location: Ireland
I think so, but plain HTML is as easy to version as an alternative. Largely I prefer Docbook because its reasonably easy to port to HTML and PDF without much effort or to CHM. Not sure which part is painful - compiling can be done on any Unix platform including Cygwin with a few lines in a makefile. As for authoring Docbook, an XML editor like XMLmind helps quite a bit as a WYSIWYG editor and a minimal set of Docbook tags (I mainly use para,sect1-3,programlisting,note and the odd emphasis. Not much else needed except for the occasional list. Remaining tags can be used as you explore the syntax but the core ones are all that really matter.# Is the pain of compiling docbook worth it? (I currently use HTML)
I think it is good to provide CHM documentation with the release. If the CHM is built properly, it can be searched (full-text), it has index, it can be bookmarked, and it can be intergrated with some programs.
the contents of CHM are just normal HTML files, resources (js/css/images) in the HTML are automatically picked by the CHM builder (which is free from MS).
It is also beneficial to provide the same documentation online where the user can add their own comments (e.g. similar to how PHP operates). Add a link in the CHM pages to the online docs.
the contents of CHM are just normal HTML files, resources (js/css/images) in the HTML are automatically picked by the CHM builder (which is free from MS).
It is also beneficial to provide the same documentation online where the user can add their own comments (e.g. similar to how PHP operates). Add a link in the CHM pages to the online docs.