ProgrammingThis forum is for all programming questions.
The question does not have to be directly related to Linux and any language is fair game.
Welcome to LinuxQuestions.org, a friendly and active Linux Community.
You are currently viewing LQ as a guest. By joining our community you will have the ability to post topics, receive our newsletter, use the advanced search, subscribe to threads and access many other special features. Registration is quick, simple and absolutely free. Join our community today!
Note that registered members see fewer ads, and ContentLink is completely disabled once you log in.
This is one of those posts where I've pretty much decided what I'm going to do anyway, but would like input from other people.
I'm writing documentation for a project I find to be quite complex. I've always run into problems documenting in HTML in the past such as parsing and making it look how I want, not spending enough time on the actual content and flow of the document. I recently decided to switch to PDF using OpenOffice.org Writer and I've come up with 60 pages of amazing (-looking) documentation over the last few days. It looks quite a bit more professional than the HTML I've come up with and it's a whole lot easier to read and to write.
The main drawbacks I see are lack of availability "right there" over the internet and the inability of some programs (such as KPDF and KGhostView) to copy text from the document for pasting into source code. An alternative to that would be to include source code files for examples, but my document currently has endless 4-line snippets to explain things.
As a developer, do you appreciate readability and convenience over quick access over the internet, possibly at the expense of being able to copy and paste? I'm open to other suggestions but I refuse to create another poll. Thanks.
As a developer, do you appreciate readability and convenience over quick access over the internet, possibly at the expense of being able to copy and paste? I'm open to other suggestions but I refuse to create another poll.
As a user of documentation I detest pdf. When using Google I always choose "View as HTML" when Google gives me that option for a pdf file.
When I write documentation I first write it as text in a text editor. Then I sometimes transfer it to html. Once a project leader asked me to rewrite some of my documentation from HTML to DocBook XML which Gnome uses as a standard documentation format.
An original format like docbook while maybe harder to write for initially will allow either html or pdf documents or info files to be produced.
I'll often download source code for a package and produce the pdf version of the manual or book from the texi source used to produce the info files. One example is "GAWK: Effective Awk Programming" which I produced the pdf version and then printed that off.
HTML sucks for printing. PDF file based documentation is easier to download from a website. If you are careful in not using funky fonts and formatting, cutting and pasting from pdf files is not a problem. However if you produce a pdf document by printing to a pdf file that may produce a poor pdf file, almost as bad as a fax image. I hate trying to read a pdf document where the diagrams are over compressed jpeg files instead of drawings that you can zoom in on.
I agree with everything that's been said, but I think I should have explained what I'm doing a little bit more.
The document I'm currently working on is really 2 user's guides in one. The first is for administrators of the system who needn't have any programming experience, but need to know how to use a shell. The second is for extension developers, but it's mainly just a quickstart so they know what in general needs to happen to create extensions, as well as a few key headers and functions.
I have a section at the very end of the current document reserved for the API reference. I've been ignoring it because I know it won't work in a PDF file. I think something mentioned above will be more suitable, probably with the help of DOxygen.
The administrator's and extension developer's quickstart guides cover fairly abstract information that's necessary in order to understand the project well enough to perform either function. I think I intend both to be used as an intro to the project (well, currently 74 pages worth) and then as a quick reference when an administrator or developer need a reminder about the internal functionality of the system. I've avoided as much actual code in the document as possible, but will probably create a "usable" API reference and manpages for the shell commands.
So I guess I've decided to go with man/info for the shell commands and something in line with the comments above (which I haven't decided on) for the API, but I do think I need a colorful, graphical, highly-formatted intro document for both administrators and developers. I've already ruled out HTML and Latex because of the "highly-formatted" requirement. Are there any other document formats that allow images, diagrams, tabs, colored/shaded text with borders, hyperlinks, etc. that actually show up as I've written them for everyone? Thanks.
PS The reason I want the intro guide(s) to look extremely professional is this is a fairly complex system that requires quite a bit of effort to understand well enough to use, and even more to develop for. I'd rather people not discard it before knowing what it's capable of because the document came out either too primitive-looking or misaligned.
PPS Sadly, the project is actually a "facility" that does nothing dazzling on its own. It will require the help of outside developers to create useful extensions for it to create large-scale modular applications. I will probably have to create a showy system of my own extensions to get peoples' attention, but that's an entirely different issue...
Distribution: UBUNTU 5.10 since Jul-18,2006 on Intel 820 DC
pdf is still proprietarily created by adobe and their later version may not be supported by linux distributions.
So while you may have no problem, I would go with HTML every time.
Also, pdf does'nt always read well - particularly when it is created by some publisher who might put 2 columns across some arbitrarily (for the end user) decided page size. An A4 print sheet does'nt for instance render well on a screen. User would have to keep scrolling back and forth and so on.
Well, here's the status. The PDF thing was great for getting the ideas out of my head, but now I don't even like updating it. Here's the plan.
I finally got around to figuring out the deal with CSS and that + XHTML is exactly what I need. It pretty much does exactly what I asked for in a previous post in this thread, but I've been editing the docs with BlueFish instead of a "WYSIWYG." I don't mind hand-writing it, and the built-in CSS and HTML guides are a huge help.
I'm going to use the above for the overview and guides and I found a DOxygen Eclipse plug-in for the API documentation. I'd never used DOxygen for C documents, but it's a whole lot less painful than using it for C++!
The project should be up and running with docs in no time. I just need a slow weekend where I can sit down and hammer out at least 2 of the 4 guides I need to write. Here's a link for now: Resourcerver
Sorry to seem like a Johnny-come-lately, but I just stumbled over this.
Glad you found a way to use HTML -- I detest PDF for documentation. My biggest bitch is that I can't zoom the display to a size that is good for my old eyes & have it stay w/in the edges of my screen. Konqueror, my default browser, can usually do this; & Opera is superb at dealing w/ the most recalcitrant cases.
BTW, please try to provide a single page ver., rather than a multi-page only -- it really facilitates searching the whole document.