Writing Documentation- Need Professional. Look

[SM_3]

I'm documenting some installation and configuration proceudres.

I need a professional look!

can anyone help?

thanks

[Michael Steele_2]

Chapter 13 of "HP Certified"
by Rafeeq Ur Rehman
ISBN: 0-13-018374-1

[SM_3]

what sort of software do I need to create this professional look.

[Michael Steele_2]

I started documenting UNIX with NROFF and TROFF but I suppose any editor like vi (* unix *) or WORD (* Windows *) will do.

[Zafar A. Mohammed_1]

1. Unix Vi with NROFF
2. Microsoft Word
3. RoboHelp

Thanks
Zafar

[SM_3]

does anyone know what HP use to create their PDF docs?

[Zafar A. Mohammed_1]

The easiest solution will be, develop all your documentation in MS Word and then convert in Adobe Document(PDF) using Adobe Distiller. Even you don't need full blown Adobe complete package, you just need distiller.

Thanks
Zafar

[John Bolene]

With Word and Acrobat, you can produce whatever documents you want.

If you want help pages, then Robohelp html or hyperhelp pages can help (LOL).

[Jon Mattatall]

I've had to do up a number of these sorts of documents for internal use, and I'd just add one point.

No matter how groovy the graphics, nothing will destroy the "professional" look faster than basic mistakes.

Spelling errors.
Grammatical errors.
Read the document. Do not rely on spellcheckers, they will not catch things like your / you're / yore.

It's a technical document, so be clear and precise. We actually give our major procedures to a student (or someone from another group) and have them perform the task on a test box to catch any ambiguous or confusing sections.

[SM_3]

It's a document for a client.

Do you have any documents I could look at, if so let me know....

thanks

[Zafar A. Mohammed_1]

I developed complete disaster & recovery document for one client. I can give your an overview.
1. CTO(IT managers) wants in a more simple easy terminology, so don't used heavy vocabulary.
2. Explain with flow & if it requires draw also.
3. Make the user-friendly document.
4. Last but not least write FAQ's also.


Now, most important just start developing and once you start all the inventing/technical ideas will come on your fingers.

Thanks
Zafar

[Michael Tully]

Hi,

It would be fairly hard to post a document even as an example. Most companies have nearly all of their documents marked as confidential.

I usually start documents with a cover page (company information and what the document is.
Document management, included version control.
Information about who the intended audience are.
Conventions, acronyms and graphical aids.
Distribution of the document and where it is held. (vitally important for DR documents.

General information (what you are documenting, system info, config etc)

Appendix - detail information disk layouts, data centre floor plans, switch layout etc

Remember system config information can be found in ignite files and can be produced using various scripts etc. You can find these in the two sysadmin script postings.
http://forums.itrc.hp.com/cm/QuestionAnswer/1,,0x026250011d20d6118ff40090279cd0f9,00.html
and
http://forums.itrc.hp.com/cm/QuestionAnswer/1,,0x836cc1c4ceddd61190050090279cd0f9,00.html

HTH
Michael

[Balaji N]

hi

did u check out tex or lyx.

Latex at

http://www.latex-project.org/

and Lyx at
http://www.lyx.org/


you need some efforts while making a document in latex. but lyx contains a XForms based interface (used it some time back, so dont remember exactly) and is called WYSIWYM (what u see is what you mean) editor.


searched the porting archive and couldnt find any pre-compiled depots for the same but u can always use the source. and if you succeed, please post me the results. have always used them on linux.

cheers
-balaji

[Roger Crettol]

I'm glad Balaji mentioned LaTeX/Lyx - if you're no absolutely short on time, you should give it a try.

-rg-

[Balaji N]

the documents i made when i moved out of my last project was done with pdflatex and the looks were pretty well.

also did a export to html and it is quite impressive.

as i say to some of my friends here, Tex rulez.

-balaji

[H.Merijn Brand (procura]

If it ain't the looks you're after, but simple fast content and flexibility, you could have a look at POD, perl's way of writing documentation. One major advantage, next to it's simplicity, is that there are a lot of converters available to create html from it.

It cannot compete to LaTex of course, but it can be an alternative.

Enjoy, have FUN! H.Merijn