Want to protect your cyber security and still get fast solutions? Ask a secure question today.Go Premium


Need Technical Writing Advice - Please Help

Posted on 2003-03-04
Medium Priority
Last Modified: 2011-04-14
Hello all,
I've been assigned my first job as technical writer on a project and am having trouble figuring out where to begin.
Specifically, I've been asked to document operations procedures for a complex heterogeneous environment involving both Oracle client/server and J2EE architectures. I must identify operations processes and procedures, determine a plausible format for ease of maintenance, and identify content and level of detail necessary to effectively educate new staff members. Additionally, I've been asked to make the documentation web accessible and searchable by keyword.

My questions are:
1) Where do I start?
2) Are there any standards, manuals or guides that I should follow?
3) Are there any websites that offer quality examples or templates I can use?
4) Based on your experience, what is the most efficient method for allowing system personnel to maintain the documentation? (Recommendations of online intranet applications/software?)
5) In terms of maintainability and search capabilities, what is the best means of publishing the documentation online? PDF? HTML? XML? Others?
As I mentioned before, this is my first technical writing assignment so any other suggestions/recommendations would be much appreciated.

Question by:HokieGuy

Accepted Solution

doddjames earned 150 total points
ID: 8081506

On the publishing and maintenance side, I would suggest a Wiki.

A Wiki in its basic form is a web site that you can edit using the web site itself.  You can format things nicely, create and link to pages etc. etc.  

You can get Wikis written in Perl, PHP etc. and there are quite a variety available, all offering different extras (in terms of security and permissioning, features such as discussion boards, blogs, etc. etc.).  You can usually create users and groups, then assign permissions against them for certain areas of the site.  One I looked at even allowed you to set up 'watches' on a web page, so when someone added information or attached a file, the 'watchers' would be notified.

They can be a bit daunting for the non-techie to set up, though.  Ask someone in tech ops whether they can find and install one for you.


Author Comment

ID: 8162554
Can someone answer my other questions?
Should this question have been posted under a different topic?

Expert Comment

ID: 9058932
This old question needs to be finalized -- accept an answer, split points, or get a refund.  For information on your options, please click here-> http:/help/closing.jsp#1 
Post your closing recommendations!  No comment means you don't care.

Featured Post

What does it mean to be "Always On"?

Is your cloud always on? With an Always On cloud you won't have to worry about downtime for maintenance or software application code updates, ensuring that your bottom line isn't affected.

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

By the end of 1980s, object oriented programming using languages like C++, Simula69 and ObjectPascal gained momentum. It looked like programmers finally found the perfect language. C++ successfully combined the object oriented principles of Simula w…
Java functions are among the best things for programmers to work with as Java sites can be very easy to read and prepare. Java especially simplifies many processes in the coding industry as it helps integrate many forms of technology and different d…
Viewers learn how to read error messages and identify possible mistakes that could cause hours of frustration. Coding is as much about debugging your code as it is about writing it. Define Error Message: Line Numbers: Type of Error: Break Down…
Viewers will learn about the different types of variables in Java and how to declare them. Decide the type of variable desired: Put the keyword corresponding to the type of variable in front of the variable name: Use the equal sign to assign a v…
Suggested Courses
Course of the Month10 days, 5 hours left to enroll

571 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question