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
Welcome to Experts Exchange

Add your voice to the tech community where 5M+ people just like you are talking about what matters.

  • Help others & share knowledge
  • Earn cash & points
  • Learn & ask questions

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

Optimize your web performance

What's in the eBook?
- Full list of reasons for poor performance
- Ultimate measures to speed things up
- Primary web monitoring types
- KPIs you should be monitoring in order to increase your ROI

Question has a verified solution.

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

Java contains several comparison operators (e.g., <, <=, >, >=, ==, !=) that allow you to compare primitive values. However, these operators cannot be used to compare the contents of objects. Interface Comparable is used to allow objects of a cl…
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 will learn about if statements in Java and their use The if statement: The condition required to create an if statement: Variations of if statements: An example using if statements:
This tutorial covers a practical example of lazy loading technique and early loading technique in a Singleton Design Pattern.
Suggested Courses
Course of the Month12 days, 13 hours left to enroll

777 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