Although many companies try to use Sharepoint, Wiki like web pages and similar to hold internal documentation, sometimes what is needed is a point in time definitive version of the documentation. A typical solution for this is to publish a word document, or to convert the web pages into a pdf file, but there are better ways.
One option I have used in the past is Sphinx, which uses reStructuredText (and now a version of Markdown) as the plaintext source for documentation. This plaintext can then be converted into whatever outyput format is desired.
Bookdown
Bookdown is built on Project-R, and hence uses RMarkdown, which other than having the ability to run R scripts, is similar to most other variants of markdown. The build process for creating a pdf file uses LaTeX as the intermediate step, but that is effectively hidden under the covers.
The source files are plain text, with a .Rmd extension, and hence are easy to version in any code repository. With the ability to run R, statistics, charts and graphs are easy to incorporate, and when new data is available, the book can be regenerated.
A nice feature of using markdown, is that to a large extent, the source text from a book can be put into this jekyll based website without any issues.
What makes the business analysis task different is that, in these types of systems, the relationships between the different attributes are partially obscured. In a third normal form database, just looking at the column names in a table lets you know the important details about that business concept. In this case, you have to trust that the grouping of the
AttributesintoCategoriesmakes logical sense without deep domain knowledge.
But some will not be immediately useful as in the LaTeX based syntax for referring to figures elsewhere in the document.
Figure \@ref(fig:PATERD) has a
Patienttable in the ERD, but the rest of the table names do not reflect the key business concepts. The reason for this is that in hospital patient data systems, many different types of readings need to be recorded about the patient, but these readings will be different depending on the type of hospital and between different units. So these types of systems tend to be locally customized to add the appropriate readings that are needed by a particular unit and associated specialists.
The above examples are from a Guide to SQL for Business Analysts, the SQL scripts in the source can be marked to either display, or to run against a database and produce a table of results. The queries run when the pdf is generated, ensuring that the SQL examples execute correctly against the database.