plan do test

Inform

Tradition

rstdoc uses documents like

• (risk) analysis (ra)
• system requirements (sr)
• detailed design (dd)
• test plan (tp)

Similar documents based on the waterfall requirement-design-implementation-verification are quite common.

But many alternative, more agile methods have surfaced, for a reason.

Evolution

A general approach starts from the evolutionary mutation-selection. Considering encapsulations, this leads to

• plan
• do
• test

until fit.

Development goes in cycles of varying size:

• all of them are pdt
• the waterfall requirement-design-implementation-verification is a pdt cycle of pdt cycles.
• usage is the ultimate test and brings maintenance cycles
• system alternatives eventually end the life cycle with deprecation, obsolescence and death/extinction

pdt is general, including the horizontal waterfall, but following cohesion, vertical cycles, i.e. by topic, are preferred. pdt is agile.

Plan

Encapsulation

pdtevolution

Creation (of a variable) and selection (of a value) in evolution corresponds to trial-and-error.

• All systems evolving, do so by trial and error.
• Every algorithm is trial-and-error. Good algorithms have less trials.

To save energy evolution produces

• encapsulations

Information flow is energy. Within encapsulations information flow is more efficient, which makes encapsulations more economic.

An encapsulation has input-processing-output. Information flow between encapsulations (input, output) is minimal:

• the interface is minimal

There are two orthogonal encapsulation lattices (topologies).

• Unit is used for the physical topology.
  • Departments and ultimately the developer are organizational or processing units. They are physical units.
  • Reality and mind are different physical units.
  • Different organizations are different physical units.
• Node is used for the content topology.

We concentrate on the content topology.

Development

pdtevolution

With shorter and less roman wording, evolution consists of make-test steps.

• creation-selection = make-test

When we consider physical units, we have e.g.

• make-test in mind: plan
• make-test in reality: do

Compared to trial-error, trial=plan,do. plan,do emphasizes the two units and the interface between them (,).

The mind needs to have a good map of reality,

• to create a plan that fits
• to minimize the interaction between these two physical units

The map of reality evolves with reality. So there needs to be feedback. The feedback is called test here.

Compared to trial-error: error=feedback=test Test is more neutral than error. It is an obvious evolutionary step of the map, to sync up with reality.

The syncing needs to happen often, if the reality changes often. The same for seldom.

Content

pdtevolution

Development is mapped to development documentation

• to organize thoughts
• to communicate with others
• to decrease the dependence of a project from processing units.
• to stay consistent over time despite
  • swap of processing units
  • memory loss of processing units

Note, that there is also system documentation, which is not considered here.

In the content topology, plan-do-test are all documentation texts, i.e. words that link to concepts, that are either up or down:

• up: more general (less variables)
• down: more concrete (more variables)

Content items are elementary nodes. They are grouped to content files or directories. All of them are content nodes.

The test is the environment of the do and gets constructed in parallel or before the do to check the do against the plan.

• plan = uplinks
• do = downlinks
• test = uplinks

plan-test forms a brace around the do.

Code is regarded as documentation using a programming language. There is no need to duplicate that with a human language.

• Human language descriptions have
  • plan: uplinks to the human context in which the system is to be integrated
  • do: downlink to what needs to be done to make the system useful
  • test: uplink to verify that what was done is well integrated
• Computer language descriptions (code) has its own pdt's with possibly many further layers
  • plan: uplink to the do of the human description arguing for a specific do on this node
  • do: downlink, e.g. via an interface, to more detailed implementation
  • test: uplink to the do of the human description using the do of this node, e.g. this interface

Content nodes are grouped

• vertically (more abstraction layers into one document)
• horizontally (by topic)

For a software project vertical groupings are

• pdt documents
• the code (possibly in more pdt groupings)

Cycle

pdtevolution

plan,do,test is a development cycle.

Cycle instead of loop emphasizes that plan,do,test needs to repeat in time.

To link the content nodes between processing units, an additional

• inform is a minimal non-technical document

Development in regular expressions is (inform plan do test )* or

1. p'=(pdt)*
2. d'=(pdt)*
3. t'=(pdt)*

• i - inform, initiate, inception, abstract, purpose
• p - plan, motivate, analyze, model, drive, optimize, qualify, why
• d - do, specify, describe, interface, commit
• t - test, verify, validate, inspect, review

If only one organizational unit is involved,

• the i is dropped. This is the case for more detailed nodes done by one developer: (pdt)*.

For mere information between organizational units

• the pdt is dropped

Method

pdttradition

Development follows the content links:

• vertical links are coherent, while
• horizontally we might just have a listing of unrelated parts

It is natural to have a development, where every cycle deals with the full vertical stack, unless the vertical links are costly.

Change of physical unit is costly. It is a change of physical unit, e.g.

• when something is physically executed
• when another developer or organization is involved

If switching physical unit is done just once, the processing unit ensures success, by simulating using its map of reality

• construct the map
• test the map
• use the map

Using the map consists of

• pdt cycles where each
• encompasses most of the vertical abstraction stack.

Traditional methods derive from the link cost.

• For software development by one or a few developers links are cheap. Agile methods are preferred.
• You build a house using the waterfall method.
• For Software, if the organizational responsibilities do not reflect the content structure, e.g. interface design by a separate organization, then waterfall is better than agile.

Despite the name in waterfall each layer is stabilized separately, i.e. horizontal development.

Processing

pdtevolution

Ideally there is one developer per pdt cycle.

A developer (initial processing unit) creates a topology on the content in a maximum cohesion - minimal coupling way.

This can be mapped to further processing units (organizations or developers). The resulting sacrifice in efficiency can be minimized, if their interactions are

• minimal, but
• still in place to operate the plan-do-test cycles

The map between content nodes and processing units should stabilize quickly and be kept stable to reduce

• information flow between old and new processing units
• memory loss (as documentation is never perfect)
• loss of methodical consistency
• reorganization of communication channels

Organizational changes are more costly than content changes.

UID

pdtevolution

Easy addressability reduces repeated formulation and thus effort.

pdt permeates down to the most detailed content, which is an atomic variable.

Detailed content items are split into 3 separate items (pdt) if there is an m-n relation between each two.

All content nodes have a UID to make them addressable. Instead of repeating, one makes a link with the UID (DRY).

The UID can be considered as a DSL word for the project domain. It is like an identifiers (IDs) in a programming language.

Infrastructure

pdtevolution

New structure builds on existing longer-living infrastructure.

• Processing units need infrastructure (e.g. office, tools, communication channels, methods, pay, ...)
• Content needs infrastructure (processing units, format, repo, ...)

The content for the development

• of one system
• is in one repo

Why:

• content encapsulation by maximum cohesion
• organizational communication
• scope for UID

A distributed VCS is used.

Why: organizationally and technically

• more independent
• less coordination needed

The repo is accessible to all physical units linked by the system (developers, users).

Why: The Repo

• is the communication hub
• is an easily findable, single point of information on the system
• avoids construction of separate communication channels
• avoids repeated interactions on costly link, especially between users and developers.

Continuity

pdtinfrastructure

Continuity is very important. Every living species on earth is

• the tip of more than 3 billion years of continuous development
• an information channel through 3 billion years of changing environments

The end of a system does not mean the end of its parts. What is part is just a question of perspective. But in general, for a system to get versatile (advanced), one needs to keep up the continuity of development.

Continuity asks for a stable infrastructure.

Do

Repo

pdtinfrastructure pdtencapsulation pdtcontent pdtuid

git is used as VCS, because it is distributed and popular.

A git branch must not contain old and new versions in parallel. Git is for versioning.

Cooperation is done over the internet via a central git repository. All branches are pushed to the central repo.

Github/Gitlab/Butbucket/SourceForge support issues.

• Issues are for feedback from the users.
• pdt documents are used for development cycles that need more planning.

Project forking dissipates effort. Repo maintainers need to react timely

• on issues or
• on pull requests

to prevent project forking.

Repo forking is part of normal development. Those without write access to the central repo,

• work on their own forks and
• contribute pull requests

The source tree tries to stay flat. Example entries:

• pdt: for pdt enhancements cycle, each in an AAA subdir
• doc: system documentation for API, libraries, GUI,...; tutorials
• c: platform neutral code in in C or C++
• python: python bindings
• test: test scripts

The build tree is outside of the repo tree.

Development Documentation

pdtcontent

rstdoc is used to a have

• all information as hyperlinked text
• documentation as python code (.stpl)
• support of many graphic DSLs
• convertibility to many other formats

Documentation as code allows to

• generate documentation from different sources (code, system documentation, development documentation)
• reuse or generate boilerplate text
• create graphics in line with text

pdt cycle documentation:

• The repo has a top level folder for pdt's (optionally named pdt)
• Every cycle gets an AAA folder below pdt, e.g. 011. Usage of base36, .i.e 0-9A-Z, keeps the UID short.
• A normal cycle has 4 documents below AAA:
  • i.rest.stpl
  • p.rest.stpl
  • d.rest.stpl
  • t.rest.stpl
• Informational entries have only an i document (pdttype).

Project-relevant content is in paragraphs with a project-wide unique ID:

.. _`xAAABB`:

with A,B base36 and x∈{i,p,d,t}.

See the sample project generated with rstdoc --ipdt tmpipdt.

A document looks like this:

.. _`i001`:

%globals().update(include('pdt.rst.tpl'
%,Title="Development Process"
%,Type="inform"
%))

.. _`i001header`:
%__i001_('header')

.. _`i001keywords`:
%__i001('key words')

Item content.

__i001() numbers the BB part. Reference to items between RST documents is done with |i001keywords|. Reference targets are not generated to allow rstdoc to create .tags that point to the .rest.stpl instead of the .rest.

i.rest.stpl contains

• pdt fields (pdtfields)
• a short non-technical introduction to the context (problem, goal, purpose).

A is a base36 letter (0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ)

pdt fields:

The necessary fields are

• PDT - The AAA pdt number
• Contact - instead of author, as the authors are documented via git
• Status - see pdtstatus
• Type - see pdttype
• Created - as a hint to how old the pdt is.

pdt status:

• drafting - work in progress
• draft - initial state until discussed and/or implemented and tested
• final - consistent with the rest of the repo or agreed upon
• replaced - for a conflicting change a new pdt replaces a final one
• deferred - possibly because other things are prioritized
• rejected - after a discussion the majority decided not go that way
• withdrawn - the one who proposed the pdt changed his mind

pdt type:

• pdt - Enhancement to the project
• inform - Informs about processes or workflows, or anything not having a pdt cycle

The inform type does not have a development phase. There can be just one file. After discussion it goes to final or another status.

Workflow

pdtprocessing pdtmethod

• First add an pdt/AAA directory to the develop branch, directly if with write access, else via pull request.
• Let peers and yourself review and change the pdt content in their local forks.
• Make pull requests until pdt status is final in the develop branch of the central repo.
• Add an AAA feature branch.
• Do development until stable.
• Merge develop into AAA regularly to stay up-to-date, and specifically before declaring that AAA is ready.
• When AAA is ready, the AAA branch is first merged to the develop branch.
• When develop is stable, i.e. tests pass, the develop branch is merged to the master branch.

Active pdt's are those where

• pdt/AAA exists in the develop branch and
• an AAA git branch exist

Done cycles have their branch deleted. Whether merged or not, the pdt/AAA folder stays.

Non-dependent cycles can run in parallel.

Plan

pdtcontent pdtcycle

plan items considers the current state:

• input from above
• experience
• examples
• simulations (separate pdt's)

plan items create alternatives by

• abstraction (analysis) and
• combination (synthesis)
• analogy

plan items motivate choice (why).

plan items are testable.

Alternatives are (stepwise) reduced to 1 choice, which is specified as do item.

(why choice test)* = (plan do test)* = (pdt)*

The ultimate evolutionary why is to save energy, i.e. one invests energy to save energy.

Why's:

• more useful (more global energy minimum)
• less effort, less cost, with same utility
• improve development efficiency itself
• in the middle of a context: produce consistency

These generic guidelines still keep many choices open. Among them

• how to group p, d and t items to minimize effort
• how to integrate products from other organizational units (qualification)

Do

pdtcontent pdtcycle

Normally for every do item there is a linked plan. do items don't need a separate plan item, if a why

• can be stated very shortly and
• is local to the do item

do items are a commitment to do things as specified.

do items only specify based on (information from) plan items.

do items are as general as the constraints from the plan items allow

do items are interface that crystalizes from the plan items

do items are testable

Test

pdtcontent pdtcycle

The test is the link back up.

• test items check against plan items
• test items are planned together with plan items
• test items are executed after the do items

Tests in lower layers are not specified.

Verification is a synonym of testing, the process of executing tests. Validations of a product from another organizational unit are the subset of tests dealing with that product.

Test-Driven Development: Tests form the evolutionary environment for a solution. One best thinks of test items when formulating plan items. This way the do items already have a environment to test against.

To make the expensive do more likely a success, one better tests early, in

• mind (thinking) or via
• via (software) experiments/simulations

As tests finalize a cycle, they are also responsible for consistency. Test items link to plan and do items, and state that their consistency has been checked.

Traceability: With separate files for inform, plan, do and test, the content items get marked as such. This can be used to automatically check that test items are linked to plan and do items.

The ultimate test is the usefulness,

• which leads to applications in the real world,
• which provides new test cases,
• leading to further improvements

A system is not bug-free, unless proven so by tests. Due to the complexity tests will

• most likely never cover everything

See

• test coverage

A system is still usable even if not bug-free. Most applications of a system use only a limited amount of functionality. Broad adoption increases usage coverage.

To reach a stable, i.e. usable, state, reserve at least as much time for stabilization as for "development", because every development step has more test steps.

With

• test driven development
• continuous integration

testing accompanies all development steps and can be considered part of development.

Test

This document is informative.

I reused the inform-plan-do-test structuring to separate

• abstract motivation (plan) and
• more concrete guidelines (do) and
• because it fits to the topic

The test is given by the application of these guidelines. It should produce feedback and adaptations in this document.

Software Project Documentation

I want to motivate the use of pure text for the central technical documents of a software project.

Many companies use DOCX, but this is no good for the technical developer folks. I have investigated and tested a way to use RST and still have a final DOCX, in addition to HTML and PDF, in case the client/company insists on it. See dcx.py.

Summary

• Minimize resource usage.
• Simplify system development to short design-testing cycles.
• Planning = Simulation. Simulate design-testing cycles.
• Requirements are interfaces. Make them minimal.
• Requirements external to the team are in the SRS else in the SDD.
• Phrase requirements as tests, or code them as unit tests.
• Generate final documents from smaller units.
• Mix human language with computer language to reduce redundancy and increase cohesion.
• The raw format of documentation should be pure text. Use RST.
• Use HTML (or PDF) as final format, not DOCX or ODT.

The Principles

Documentation in a project is written communication to be preferred over oral.

Documentation is not the goal per se but the means to the project's goal.

These general principles apply also to documentation:

• A system develops by mutation and selection or creation and selection (= evolution). The selection is the verification or testing by the environment.
• Maximize cohesion and minimize coupling. The amount of coupling is a metric of locality and should be reflected in the documentation artefacts. Coupling and cohesion are synonyms.
• A system is developed by a divide and conquer approach. Units are characterized by a separate evolution. There is a hierarchy of units.
  • Units have requirements (purpose, coupling, interface) to the system they are part of.
  • Units can be and must be tested separately (unit tests).
  • Units have an internal complexity larger than the interface.

• Minimize redundancy, i.e. don't repeat yourself. To this purpose:

  • Develop concepts (units) and words for these concepts, i.e. a language specific to the system.
  • Make paragraphs (units) that have only one aspect.
  • Give every paragraph an URI.
  • Link concepts and paragraphs by using the words or URI's.

  URI's, for efficiency, must be accessible by a direct jump (via mouse click or a keyboard shortcut).

The latter three follow from minimize resource usage: memory and time of the computer and the developers.

Evolution

Evolution governs all dynamical systems: our brain, teams, ...

The basic step in evolution is to select an element from a set, which translates to fix a value of a variable. The set or variable needs to be created. So there is creation and selection.

The values of a variable are its type. Type, in a certain aspect, is synonymous to variable. But due to the (often unmotivated) reuse of the same set of values for different variables, one needs a way to reference these values by a different name, which is type.

Variables are the elements of information processing, which also mathematics deals with in the foundational frameworks of set theory, type theory and category theory.

Variables and types are the essential elements of a human languages and of programming languages, be it procedural, OOP or functional.

modelling

A hierarchy of variables of the actual system is mapped to a hierarchy of variables in a (programming) language, normally with simplifications.

Of the system development lifecycle I subsume planning, analysis and implementation in the design process. As an important separate part there is the testing (stabilization). Design-testing are the cycles of evolution. One can also call it Trial and Error.

design

= creation. create variables, units, concerns, interactions, ...

test

= selection. select (yes/no) and improve.

Design and Testing repeats in a layered way, until reaching a stable software, everybody is content with.

The Design and Testing is parallelized to team members as soon as the major units have been identified. There is no individual designer or architect, because that would serialize and thus slow down the evolution.

There can be a quality manager to streamline methodology and communication.

It is important, that everyone can make proposals. The quality manager needs to instantiate channels to facilitate that.

Planning

Planning is evolution in the mind. Planning (far ahead) is simulation.

Constructing variables in the mind is less effort than constructing the real variables like hardware units. Simulation becomes more important with the probability that designs will be dumped, if the testing fails, and with the difference in effort between real construction and simulation. Physical constructions should be well planned and simulated. The real design and testing is best delayed as long as possible.

The mind is not powerful enough to simulate complex systems. But it works with the help of computers.

With software, simulation is not necessarily so important, because SW elements often follow directly form concepts of the mind without extra effort like procurement and physical treatment. But if other OS components (executables, libraries) and communication to other programmers and teams are involved, the effort immediately rises. To minimize this effort, one simulates such interface components (mock, stub). The mocks are made at an early stage and are preferably make a part of the requirements (Test-driven development = TDD).

A single developer should also mock the bigger ones of his own interface components,

• to have a consistent TDD approach, where developer assignment is transparent
• to allow parallelizing through reassignment of subunits

The Documents

The raw format of documentation should be pure text.

Documentation that accompanies and coordinates the development of software (or generally system) from requirements to testing, is intricately interwoven with the software, not just in one direction.

• There should be no tool barrier between the source code and the documentation.
• Formatting has no importance and especially during development you should not be concerned about it (Separation of Concern = SoC).

Note

Software/System

Software can be replaced by System, because non-software systems can also be described by source code in a domain specific language and it is a good approach to do so, instead of using a GUI-only software package.

A coarse hierarchy of units is mapped to teams, a finer one to individual developers, which then produce the finest granulation of units.

Documentation is especially important as a means of coordination between teams and individuals. These are the

• Software Requirement Specifications (SRS).

The requirements come from the environment (= context), i.e. the bigger system.

A system is described by the

• Software Design Description (SDD). The result of the design is an architecture.

So SRS and SDD are linked, but

• only requirements external to the team are in the SRS.
• internal requirements are part of the SDD.

Tests accompany all units throughout the hierarchy.

For cohesion,

• unit tests are part of the SDD,
• the requirement tests are part of the SRS.

Actually it is convenient to immediately phrase requirements as tests or code them as unit tests (TDD).

Since there are more aspects of testing, a test team will have a

• Test Plan

that can reference SRS and SDD tests, and thus avoid producing redundancy, but will have additional tests, too.

We see that the hierarchy of units is not mapped to a hierarchy of documents, at least not in the same granularity. But this actually breaks the cohesion.

• Separating documentation from source code produces more links, i.e. more URI's are necessary. The natural ordering is that of the units.

By generating final documents from smaller units, one can have both, cohesion by aspect (SRS, SDD, Test Plan) and cohesion by units.

Initiating the Development Process

The SRS is an interface document between teams:

• the development team
• an outside entity

It is essential input for the development. It should therefore be an integral part of the documentation of the development process. Therefore the final version of the

• SRS should be written by a member of the development team.
• Both parties will negotiate and will agree on a final version and will also agree on future reviews.

The content of the SRS

• does not describe the system to be developed, but its context, the way of its operation, its usage in the bigger system. In case documentation about the bigger system is available (e.g. if internal), a link will do.
• The requirement paragraphs must
  • address a well confined unit (of the interface to the bigger system)
  • be verifiable

  • be referenceable via a hyperlink URI

    The URI is important, because during development decisions will need to be justified by a reference to the SRS entry.

Design

In the SRS the context (bigger system) must be analyzed, i.e. split into a suitable parts and concerns and written in paragraphs of single concern (implemented)

Test

Verify that they can be tested and easily maintained. Phrase requirements as tests.

• As an interface document the SRS must satisfy the minimal coupling principle, i.e. it must be minimal.

  Requirement paragraphs should link to other documents that support the requirement, as a measure to ensure that no unnecessary requirements are specified.

  Optional things are not in requirement paragraphs but in surrounding text.

  Every small requirement change late in the development can entail a huge effort, if it means changing a complex system, since that will need a long time to stabilize again.

  It is often easier to change requirements in case of obstacles encountered during development. But if the SRS is kept minimal, one can normally do without.

• The SRS must be open for changes, if at an early stage of the system and thus not yet thought through in detail. In this case the SRS will be modified during the development process. The coordinating development team member will agree on the changes with the outside entity in SRS reviews.

Development

Often the approach is to model in a human language first and then "translate" that to a computer language, i.e. implement it.

But specifying variables and relations is what computer languages are good in and made for. So many parts can be coded in a computer language right away at the component level. Higher language generations can be made very readable.

It is a good idea to mix human language with computer language to

• minimize redundancy
• maximize cohesion, independent of whether human or computer language is used

There are two approaches to do this:

• embed computer language in human language (literate programming)
• embed human language in computer language (documentation generators)

The second approach is more popular. The reason is, that computer languages allow quite well to split conceptual things from implementation details. Files that contain variables and values of the model can also contain additional human language in comments. Such files can be

• used directly by the compiler
• parsed for parts to be incorporated in the documentation

To incorporate code comments in the documentation in a selective fashion, it is good

• to use a light markup text, like RST

• to script one's own way to extract those parts from the source code files

  The available documentation generators tend to be targeted to specific applications, like creating an API reference, and thus are not flexible enough to exploit the full potential of the principle approach.

Light Markup

The advantages of light markup formats:

• It allows mixing source code with documentation for better cohesion and less redundancy.
• It can be easily learned, because it restricts itself to essential elements.
• The elements are of conceptual nature (header, list item, ) not actual formatting. The formatting is done when creating the final document. This makes it easier to keep a consistent formatting when more people work on the documentation.
• As text it, is perfect for version control systems. One can commit documentation changes together with the according source code changes. It is easy to review documentation changes. It allows to keep outdated information without lying around and messing up.
• It is easier to generate parts of the documentation with scripts from source code or source code comments
• It is easier to extract data from the documentation, like which items link to which other ones, especially if the team agrees on facilitating conventions.
• It can be edited with a text editor, i.e. the same tool developers work with all the time.
• It is accessible to grep.
• Ctags can be used to jump around while editing.
• It is very readable as source and can be translated to several final formats, e.g.
  • HTML, most importantly
  • PDF (pandoc, sphinx)
  • ODT, DOCX (pandoc)

RST

There are many light markup formats. But especially restructuredText (RST)

• has rich format support (e.g. table formats)
• is extensible
• is best for python scripting
• has a very good tooling support
  • Pandoc (to HTML, PDF, DOCX, ...)
  • Sphinx (to HTML, PDF)
  • Docutils This is used by sphinx, but allows for own scripts, and has separate rst2html script.
  • Ctags support to jump around while editing

http://rst.ninjs.org can be used to play with RST. Here a cheatsheet.

Dealing with Company Tradition

Unfortunately companies often bury information

• by not using pure text
• or by using text that needs special tools (like over-formatted XML).

At three of the companies I worked for, they used MS Office for documentation, at one they used Lotus Notes.

The problems I see are the following:

• They are too detached from the other text project artefacts.
• They don't have the idea of an URI for every resource.
• Thus they cannot be linked well via hyperlinks.
• They are not suitable for a version control system: diffs do not work well.
• A proprietary format is no good for the company's precious information. The information gets locked. Even it being standardized does not change that, because the adoption by the developer community is reluctant and thus independent tools are rare.
• DOCX or ODT is not easily accessible to scripting, because libraries are rare and also because DOCX is XML that mixes formatting with content. HTML with CSS and XML with XSLTs (e.g. Docbook) separate better and are more accessible to scripts, but less suitable for direct editing, because too formal and needing more learning.

Thanks to Pandoc and Sphinx it is possible to use text as the documentation source and still fulfill the company's requirement for DOCX.

Providing DOCX from RST

HTML is the normal target of light markup formats. It is also best for the URI principle. Nevertheless it is also possible to generate DOCX.

For the conversion from RST to DOCX currently the best tool is Pandoc, Pandoc only takes pure RST and does not know about the Sphinx role extensions like :ref:. For that, one would need a sphinx-docxbuilder.

I have investigated and tested a way to use RST and still have a final DOCX output, in addition to HTML and PDF. dcx.py is used as a support script.

• Don't use Sphinx specific roles, like :ref:.
• :math: is supported well. It is not a Sphinx extension.
• Top level files use extension .rst. Included files use extension .txt (.. _include: somefile.txt)

• Make paragraphs with target ID this way:

  .. _`targetid`:
  
  :targetid:
  
    Text follows here.

  targetid is lower case, because docutils converts targets to lower case.

• As the link differs between HTML and DOCX, use replacement substitutions (|targetid|) as links.

  A links_docx.txt file with entries:

  .. |targetid| replace:: `targetid <file.docx#targetid>`_

  and a links_sphinx.txt with:

  .. |targetid| replace:: :ref:`targetid <file.html#targetid>`

  will define the substitutions separately.

• Above headers there can be some unique target ID:

  .. _`secondminutedate`:

  Links using |secondminutedate| will replace the header for the target.

• Substitutions cannot be in included files, until the Pandoc include bug is corrected. For the links_docx.txt this helps:

  cat file.rst links_docx.txt | sed -e's/.. include:: links_sphinx.txt//g' | pandoc -f rst -t docx -o file.docx

  For image substitutions to work place the .. image:: xxx.jpg into the main rst files, before the .. include:: links_sphinx.txt.

For an illustrative implementation of these guidelines see dcx.py.