Re: DOCBOOK: Re: <remark> and <para>

[Stephen Rasku <stephen@tgivan.com>]

Norman Walsh wrote:

>/ Stephen Rasku <stephen@tgivan.com> was heard to say:
>| I notice that <remark> doesn't allow <para> as a child.  I would 
>| like to do multiple paragraph comments.  Is there a way to do this?  
>| What is the rational to not allow <para> in <remark>?
>
>How are you using these comments? (I'm just curious.)

It is a template for internal documentation.  The comments describe 
what is supposed to go under each heading.  Currently, they are 
formatted using standard tags but some employees were confused as to 
whether to leave them in the document or not (they shouldn't).  I'll 
attach the version we are currently using.

-- 
Stephen Rasku			E-mail:	stephen@tgivan.com
Senior Software Engineer	Web:	http://www.pop-star.net/
TGI Technologies
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<article class="TechReport">
<title>Feature Plan Outline</title>
<artheader>
<author><firstname>Firstname</firstname><surname>LastName</surname></author>
</artheader>
<sect1><title>Project Name</title>
<para>Give the project a snazzy name so everyone can identify the work.</para>
</sect1>
<sect1><title>Motivation</title>
<para>Succinct statement of what this work will accomplish for the product.
Detailed project rationale and history should be attached as Appendix.
(E.g., Appendix would cite a contract obligations, list of bug reports,
cores, etc.) </para>
<para>E.g., IRAP calls for triggers. This project fulfills the the general requirements. See Appendix A for IRAP compliance analysis vs. the deliverables outlined by this project.
</para>
</sect1>
<sect1><title>Problem Description</title>
<para>State in engineering terms the problem(s) solved by executing the development of this feature or project plan.</para> 
<para>E.g., Today the DMD can not handle anything but an incoming or outgoing Class 2 fax. This project will add voice and data. This means the DMD can drive an appropriate fax, data, voice digitization modem ....</para>
</sect1>
<sect1><title>Recommended Solution</title>
<para>State the design or implementation features and approaches recommended
for solving the "problem(s)". </para>
<para>E.g., sn_ol is an interim step to full Open Windows Look and Feel compliance. We'll use the sun
view to xview toolkit to convert .... </para>
<para>Alternate Solutions Considered (but Rejected)</para>
<para>Defend your recommendation. Cite work researching alternates, including in-house brainstorm ing sessions and industry white papers. Summarize the pros and cons and while deferring any in available in-depth analyses for an Appendix (B). State the heuristics applied against </para>
<para>E.g., We know that going full Open Windows Look and Feel is good for Solaris branding reasons, but it means SCINET 3k has two differing presentations and pragmatics for the user. Also, full Xlib implementation may be more portable, but MUCH more costly than anything else. So we chose xview for now.</para>
</sect1>
<sect1><title>Statement of Work</title>
<para>Section defines an unambiguous list of deliverables, as semantic input to the feature schedule.  Deliverables are detailed enough so there's no question of when each is complete. Moreover, the project's schedule is derived from this statement of work. </para>  
<para>Deliverables include:</para>
<orderedlist>
<listitem><para>Design Documentation.</para>
<para>
New projects should comply with IEEE 1016 Standard for Design Documents.
Its Section 5 has an outline which should be followed. It's a very good
organizational tool that will really help us improve our product at the
design phase. That's the cheapest way to build in quality.
</para></listitem>
<listitem><para>Implementation Documentation citing:</para>
<orderedlist numeration="loweralpha">
<listitem><para>source modules and languages used to implement the
design. These include heuristics to decide function and include file
"packaging".</para></listitem>
<listitem><para>build procedures so that source modules are integrated into a succinct product build.</para> </listitem>
<listitem><para>order of development for processes, data structures, and
functions (or source modules).</para></listitem></orderedlist></listitem>
<listitem><para>Feature Documentation -- Internal: </para>
 <para>Cite documentation deliverables meant for Engineering and support eyes.
</para>
<orderedlist numeration="loweralpha">
<listitem><para>man pages (even for functions shared by multiple execs,
as well as the execs, per se.)</para></listitem>
<listitem><para>release notes: </para>
<para>Explain what libraries and executables are enhanced, what bug reports or cores are solved, and what product behavior may support people expect.</para>
<para>E.g., libconvert.a had bugs 100, 302, and cores dmd/Sept/19 against it's attempt to convert TeX into Postscript. functions foo() and bar() redesigned to solve bugs, add in font sizes, and fix problems with structured programming. </para></listitem>
<listitem><para> packaging requirements: </para>
<para>how does resultant binaries get onto a tape.</para>
<para>E.g., mklicence does not appear on tape. It's strictly TGI internal.
</para> </listitem>
<listitem><para>test plans and test cases: </para>
<para>Show how individual functions are tested, especially the input forcing your subject functions to run in situ within the product. </para> 
<para>E.g., send fax "foo" ... forces my_send_routine() to call my_dmd_special() with "9,411". But send fax "foo" at time "bar" forces my_qmd_buddy() to call my_send_routine().  Writing the test plan produces explicit test data files and a list of interfaces and interface permutations for testing. 
Executing the test plan produces test results and observations, which
are also deliverables. </para></listitem></orderedlist></listitem>
<listitem><para>Feature Documentation -- external: </para>
<para>Cite documentation deliverables meant for Customers and Customer Support
consumption. </para>
<orderedlist numeration="loweralpha">
<listitem><para>changes to installation notes.</para></listitem>
<listitem><para>changes to manual.</para></listitem>
<listitem><para>publishing (changes to) man pages of "public" interfaces that users or third party vendors see.</para> </listitem></orderedlist></listitem>
<listitem> <para>Deliverable Reviews:</para>
<para>Reviewing work in progress against the deliverables is critical, and especially valuable are critiques by your peers. Often their perspective and ideas can keep you from calamity. </para>
<para>Plan for reviews on the following levels:</para>
<orderedlist numeration="loweralpha">
<listitem><para>Prelim Design review of the project's solution models
and interfaces. Here you should be able to defend the number and nature
of the processes, functions, and interfaces for your design.</para></listitem>
<listitem><para>detailed design on module by module basis. Your should be
able to walk through English language descriptions of your functions and
defend their structure and capabilities. These descriptions are left as
comments in the body of your code.</para></listitem>
<listitem><para>code reviews. defends the C implementation, its
adherence to the original detailed design,  TGI standards, structured
programming, and  the level of in situ documentation.  Someone should
take notes, including recording actions assigned during the review.
These notes and completing these actions are deliverables, too.</para></listitem></orderedlist></listitem>
</orderedlist>
</sect1>
<sect1><title>Schedule Estimates</title>
<para>Estimate each deliverable item in work weeks, assuming 100%
effort. Cite additional assumptions including tools and support from
other people.
</para>
<para>Your Statement of Work and this schedule are tied directly. Each
deliverable and their details should appear in this schedule. Use this
heuristic: no single scheduling item should weigh more than 10 or 15% of
the total. Otherwise, your schedule is risky because your planning is
not complete enough.
</para>
<para>Also, don't forget to include review time. Design reviews, code
reviews, and extra time to followup on the actions and changes derived
at these reviews!
</para>
</sect1>
<sect1><title>Appendices</title>
<orderedlist numeration="upperalpha">
<listitem><formalpara><title>Detailed Project Justification</title>
<para>You want to state the problems and challenges as defined by
contractual obligations, product strategic plans, bug lists, cores,
etc. </para>
</formalpara></listitem>
<listitem><formalpara><title>Detailed Defense of Recommended Solution</title>
<para>You want to prove that multiple reasonable alternatives were
considered besides the engineer's recommendation. This section holds the
design decision rationale used by engineering.
</para>
</formalpara></listitem>
</orderedlist>
</sect1>
</article>