repost: ODE structure notes


Wade Hampton (whampton@staffnet.com)
Mon, 10 Jan 2000 14:32:08 -0500


To interject more confusion, I have a few comments.

I recently implemented a document scheme and hierarchy
for a customer of mine. The scheme is designed to
organize and index hundreds of documents by multiple
vendors in several formats. As such, it is a micro
version of what ODE could be (but it is much
more rigid). I have been using many of these concepts
for nearly 6 years to maintain hundreds of documents
comprising thousands of pages. All are under version
control and coordinated among multiple vendors (all
is in-house and most is proprietary).

A similar (but larger and looser) framework could be
created for this effort. This framework should have the
following objectives:

1. support existing documentation
2. support multiple document types (with recommendations)
3. support open source documentation under multiple licenses
4. support multiple operating systems including commercial (e.g.,
     Windows, SGI, etc.)
5. support proprietary documentation (e.g., by reference only or by
    abstract)
6. provide recommend formats, naming, and standard meta-data (e.g.,
    author)
7. encourage the creation of new documents, notes, howtos
8. be flexible and expandable.
9. be VERY simple for creation of technical notes or simple howtos
    to encourage their generation/maintenance.

More requirements:

1. Tracability -- where did the document originate
2. Version control -- on-line copies of previous (relevant) copies
3. Security -- ability to sign documents or validate documents

An acid test would be to ask if any environment you design
would be applicable in 6 months, 1 year, 2 years. Look at the
Internet RFCs. That simple scheme is very old, but still
being used and is effective.

Implementation steps:

1. define the overall requirements (a draft statement of need)
2. define a draft framework, e.g., expand on the list below
3. get comments and review by others from other groups (GNU, BSD,
    vendors, etc.)
4. get others to join the group (list of supporters and associates?)
5. develop framework version 1.0
6. develop the standards (e.g., ROPs)
7. get copies/links to tools, develop tools where needed
8. build one or more databases and/or search engines
9. import/convert existing docs and roll out the ODE

The outline below details some of this concept:

A. supported formats
        - manual pages
        - short ASCII text pages (e.g., some Linux kernel docs)
        - HTML
        - DocBook
        - SGML
        - gnu INFO
        - pdf (e.g., for legacy or external docs)
        - ps (e.g., for legacy or external docs)
        - other (wp, word, spreadsheets, etc.)
        - each should have a filter for format -> printable,
          format->html, and format->searchable

B. tools -- recommended set of tools for each supported format
        - document type X to html, ASCII, ps
        - search and index tools
        - man template and parser
        - ps2pdf
        - sgmltools
        - docbook tools
        - man2html
        - info2html
        - tool to get docs from RPMs and other packages
        - etc.

C. document authoring guidelines/procedures
        - a document or documents describing the meta data, formats,
tools...
          (e.g., ODE-ROP-ALL-MAN-001-01 -- describe man page formats,
tools...)
        - document number format (for indexing purposes), e.g.,:
                ODE-TYPE-OS-SYSTEM-SUBSYSTEM-NUM-REV
                  ODE -- fixed text, identifies as an ODE document
#
                  TYPE -- RFC, STD, ROP, SOP, DOC, SECURITY
                  OS -- LINUX, FreeBSD, Solaris, etc.
                  SYSTEM -- ALL, RedHat 6.x, etc.
                  SUBSYSTEM -- MAN, or Apache,
etc.
        - document indexing info
                -- author
                -- organization
                -- license
                -- date
                -- version
                -- author's document number (e.g., RFC-822)
                -- type
                -- index document number (per above)
                -- may_copy (Yes or No)
                -- source link (URL)
        - recommended procedures for each document type
        - recommended tools for each document type
        - samples and templates of each document type
        - server with above....

D. documents (by group)
        - recommended operating procedures (ROP) [e.g., do not run as
root+why]
        - security (SOP) [e.g., use of portsentry to monitor your
network]
        - howto (HOWTO)
        - manual page (MAN)
        - technical note (TN)
          [e.g., /usr/src/linux/Documentation/sound/Introduction]
        - on-line book (BOOK)
        - RFC, STD, etc. [e.g., Internet RFC's]
        - interface documents (ICD)
        - design documents (SDD, etc.)
        - comments (COM)
        - application (APPL)
        - system-related (SYS)

E. members, organizations, related projects:
        - Linux KB
        - LDP
        - BSD folks
        - vendors (e.g., RedHat, Caldera, SuSE, Debian, VA, etc.)
        - individuals

Comments anyone?

-- 
W. Wade, Hampton  <whampton@staffnet.com>  

Linux is new, it's come out of nowhere, it's free. Hard to beat that price. And it's taking marketshare left and right.

--Microsoft's lawyer, in closing argument, Bristol v. Microsoft, http://www.microsoft.com/presspass/bti/07-15closing.htm



This archive was generated by hypermail 2.0b3 on Mon Jan 10 2000 - 14:33:32 EST