An example template of files for variants of a solution architecture in a documentation-as-code approach ... video
The provided content leverages several technologies ... video
- The text-based structure/format is in AsciiDoc ( https://github.com/asciidoc/asciidoc ) format (see/edit *.adoc files) and can review a simple tutorial ( https://github.com/bwgartner/AsciiDoc-to-DAPS)
- the default structure is generic e.g. classic book - chapter - section - sub-section
- other variations are also available ... video
- Enterprise Architecture - ReadMe-EA.md
- Reference Architecture - ReadMe-RA.md
- other variations are also available ... video
- much of the sample text placeholder content is from the generic Loremipsum generator, so this is where you substitute your content.
- many templates also have built-in comments to help express what aspects to cover
- NOTE: focus on anything that cites "FixMe"
- the default structure is generic e.g. classic book - chapter - section - sub-section
- To create any number of multiple output formats, install and leverage DAPS ( https://github.com/openSUSE/daps )
- html, single-html, pdf, epub
These quickstart steps validate you have what is needed to begin your content iterations ... video
- Obtain this document's template content
- git clone "ThisGitHubRepoURL" (to make a local copy)
- download either master (zip) or the latest release (zip/tar.gz), then unpack it
- cd to your local directory where it landed and was uncompressed
- Test that you have all the tooling in place to generate an output
- e.g. daps --force -d DC-SA html
- test with a web browser, open the file:///localDirectoryName/build/SA/html/SA_draft/index.html
- Review examples to create and view some sample outputs
Elaborating a bit further, to highlight the modular aspects of the various template artifacts and how to use them.
- At this point, you can now start editing the configuration/structure/content to meet your needs
- NOTE: every portion of text that cites "FixMe" is a flag to encourage modification
- in the top-level directory
- for the default configuration/structure (chapter/section/sub-section)
- review/edit the DAPS configuration file DC-SA ... video
- NOTE: if you prefer to have a more specific output file name, copy DC-SA to DC-YourPreferredOutput (and use that name change for any of the following "DC" references)
- comment out any ADOC_ATTRIBUTES line to skip that respective section
- uncomment any ADOC_ATTRIBUTES lines and set the value to 1 to include the respective content
- review/edit the DAPS configuration file DC-SA ... video
- for the default configuration/structure (chapter/section/sub-section)
- in the main "adoc" directory
- review/edit the adoc/SA.adoc main file that pulls in the selected sections ... video
- if the respective ADOC_ATTRIBUTES value is set (value = 1 and uncommented) in the DC-SA file, then the conditional "ifdef" will include that content in the output
- if you need fewer chapters, feel free to comment out the extra "include" of chapters 2 (ii) - 7 (vii)
- review/edit the adoc/SA_vars.adoc file to change global variable settings ... video
- useCase
- companyName
- title (relative to your attribute setting)
- author information
- github references
- review/edit the general sections, that are generally included
- review/edit the general sections, that your ADOC_ATTRIBUTES settings will include
- adoc/SA-References.adoc
- adoc/SA-Appendix.adoc in the various chapter directories aka Roman numeral sequences
- review/edit the chapter/section/sub-section content, that you wish to include
- adoc/i/SA.adoc aka Introduction
- adoc/ii/SA.adoc ... video
- etc
- review/edit the adoc/SA.adoc main file that pulls in the selected sections ... video
- as you edit the modular text content snippets, create an output format
- daps --force -d DC-SA "format" ... video
- where format might be "pdf", "html", "html --single", "epub"
- then review the output and continually iterate until you have your content complete
- daps --force -d DC-SA "format" ... video
- miscellaneous
- you can also add images/media content as needed in those subdirectories
- do not forget to check in your iterations as well to have a source repository and ability to rollback to a known working state
- feel free to provide feedback, ask questions or even submit pull request