arc42 / arc42-template Goto Github PK

It seems that the build does not work on a *nix OS

A colleague and I were wondering the following today: the documentation that one maintains based on this template is a living thing, and thus all the sections will be corrected and extended as the solution being built evolves. Is there a way to reflect the desired (maybe even utopic) architecture that we want to achieve, and at the same time document the status quo?

a5da1d6

It seems to still work, but some clean ups have been removed

me <- should get more git practice

to setup an empty asciidoc-based arc42 as simple as possible...

see https://github.com/pledbrook/lazybones

... does not export diagrams which are sub-elements

would be nice to have a github page with a nice "landing zone" - and maybe forwarding to confluence.arc42.org

we need more documentation for the toolchain itself, all steps of the toolchain and how to use them

In meiner Schule benutze ich LaTeX um Dokumente erstellen und zurzeit dokumentiere ich ein Projekt von mir mit arc42. Deshalb habe ich eine Vorlage in LaTeX für eure Architekturdokumentation erstellt. Sie befindet sich auf Github unter folgendem Link:

https://github.com/wuethrich44/arc42-latex

Ich hoffe das ist oke für euch (Lizenz) und wenn ihr wollt könnt ihr das Template bei eurem Wiki hinzufügen. Ich werde das Template laufend an das Confluence-Template anpassen und bei Bedarf noch eines für Englisch hinzufügen.

as discussed between @rdmueller and myself during JAX-2015

• content-repo contains the master versions of the template in asciidoc, including help text
  and all required meta information, in all supported languages.
• content-repo contains a build that generates html versions of the available languages
• generator-repo takes the content from content-repo and creates the various output formats
  (html, pdf, docx... with and without help, including one or several build-files for every version
• generator-repo moves/pushes the output of its build to the landing-page-download-directory...

does that sound plausible?

Konzepte-Themen primär als Checkliste aufnehmen, keine weiteren Erläuterungen mehr.

In order to use the template for grails projects withouth asciidoc, a gdoc template is needed. gdoc is a subset of textile...

create subprojects for

• DE version
• EN version

and "master build.gradle"

currently we only generate html into our build directory.

It'd be nice to copy all downloadable artifacts (e.g. the manually maintained EAP format, any manually maintained docx format, etc to the download directory, together with hashes etc

calling gradle in top-level directory (beneath master build.gradle) produces the following
error:

(seems to be a simple build-path problem)

$ gradle arc42
./src/DE/asciidoc/plain-without-help/./.DS_Store
./src/DE/asciidoc/plain-without-help/./build.gradle
java.io.FileNotFoundException: ./src/DE/asciidoc/golden-master/./src (Is a directory)
./src/DE/asciidoc/plain-without-help/./src/appendix-examples.adoc
./src/DE/asciidoc/plain-without-help/./src/appendix-practitioner.adoc
./src/DE/asciidoc/plain-without-help/./src/arc42-template.adoc
./src/DE/asciidoc/plain-without-help/./src/kap01.adoc
./src/DE/asciidoc/plain-without-help/./src/kap02.adoc
./src/DE/asciidoc/plain-without-help/./src/kap03.adoc
./src/DE/asciidoc/plain-without-help/./src/kap04.adoc
./src/DE/asciidoc/plain-without-help/./src/kap05.adoc
./src/DE/asciidoc/plain-without-help/./src/kap06.adoc
./src/DE/asciidoc/plain-without-help/./src/kap07.adoc
./src/DE/asciidoc/plain-without-help/./src/kap08.adoc
./src/DE/asciidoc/plain-without-help/./src/kap09.adoc
./src/DE/asciidoc/plain-without-help/./src/kap10.adoc
./src/DE/asciidoc/plain-without-help/./src/kap11.adoc
./src/DE/asciidoc/plain-without-help/./src/kap12.adoc

so we can generate:

1. full version, with all content and explanations
2. skeleton version, with all headings, without explanations

eventually:
3. customized version

the asciidoc versions of the template shall be copied to our build (= output) directory.

From that, we'll create the download-artifacts one day...

I created a nabble-forum:

http://arc42-discussion.1007769.n3.nabble.com/

which we could integrate here at github (and later also in arc42.de and .org)...

Any suggestions how/where?
(yep - gh-pages would be great for that, also an arc42.github.io page, which currently does not exist...)

An image reference in 09_design_decisions.adoc results in a wrong width attribute

the build script currently ignores the en-version.

Have to update some parts in order to generate DE and EN versions of the templates

im Zuge des Buchprojektes "arc42-in-Aktion" haben Peter + ich die Erläuterungen ziemlich aufgeräumt... das mal in einer neuen Version nachziehen...

. arc42-template.adoc, introduction
The explanation of the "version" should differ in plain and golden-master (formerly plain-with-help):
** plain: Dies ist die plain Version des Templates, ohne Erläuterungen...
** gm: Diese Version des Templates enthält Hilfen und Erläuterungen....

.arc42-template.adoc, concerning appendices
** plain: should imho not contain any appendix
** gm: should contain all appendices (references, contributors, examples etc.)

what about having the arc42-template.adoc in two different versions.
The "plain" version will be copied together with the "createTemplateWithoutHelp" target...

see #33

should be an extra option, not a default

Comment by @plafuro : The contributors page has also a small bug, by the way (the blue header is missing, as its url points is relative, where it should be absolute: "/resources/arc42-site-banner-striped-blue.jpg")

in directory "plain-without-help", all "Umlauts" are causing non-UTF-8 aborts with asciidoctor (on Mac OS)

Seems we have a Windows/Mac issue again...

so that prosective users can immediately start...
(with at least java or maven installed)

now that the build generates formats and zip files which should include images, the image copy task has to be fixed.

what better opportunity to apply arc42 to itself :-)

recursion-is-king, we know that since Lisp was invented.

Therefore: in docs directory, let's start a small collection of architecture information...
(EAP-export should be a level-1building-block in our "building-block view".

other option: create directory named "design-decisions" and writeup your ideas/approaches
in adoc in a file in there.

g'nite and thx for your effort - I really appreciate it,
Gernot

Please take a look at the installed template for aquagrails:
https://github.com/arc42/aquagrails/blob/master/src/docs/arc42-template.asciidoc
it contains a special header which gets only rendered on github and which lets you navigate through the sections.
It also contains the text "place your own documentation here and remove the help text below as soon as you are ready." - for me as someone who doesn't know the template by heart, it is quite helpfull to have the description of the section right at hand until I've finished the documentation of the section.

What do you think? Should be include those features in the original asciidoc template?

...but I guess it only makes sense for the with-help version

let's finish the travis script in order to get deployed templates

Zu dem Dokument hab ich ein paar Anmerkungen:

1.  In dem Kapitel 8 (übergreifende Konzepte) könnte ich mir gut vorstellen, noch weitere Unterkapitel
   

zu haben: Kandidaten sind aus meiner Sicht Batch-/Stapel-Verarbeitung, Drucken, Reporting und Archivierung.
Ich hab das in meiner Fassung mal ausprobiert, und auch ein paar (unsichtbare) Fragen dazu formuliert. Feel free…J

2.  In der speziellen XY (Nachdokumentations-) Situation haben wir festgestellt, dass es für den
   

Leser sehr hilfreich sein dürfte, wenn man ein Kapitel „Einstiegshilfe“ hätte.
Natürlich ist die Architekturdoku an sich schon eine Top-Down Einstiegshilfe. Ich hatte darüber hinaus
den Vorschlag gemacht, bestimmte Klassen und Methoden tabellarisch aufzulisten, die man kennen/nutzen
sollte, wenn man bestimmte (absehbare) Änderung am System vornehmen möchte.
Dazu zählen insbesondere komplexe fachliche Berechnungen, oder
Interfaces die bei Erweiterungen implementiert werden sollten, oder …. uswJ

Bei uns lautet das so:
12.Einstiegshilfe
In diesem Kapitel beschreiben wir Stellen im Code anhand von Klassen oder Methode, an denen wichtige fachliche Funktionalität implementiert ist und/oder die im weiteren Lebenszyklus der Anwendung potenziell geändert werden.

Excuting gradlew under Java 8 fails:

d:/src/arc42-template $ ./gradlew.bat
Downloading https://services.gradle.org/distributions/gradle-1.12-bin.zip
...........................
* What went wrong:
A problem occurred evaluating settings 'arc42-template'.
> java/util/HashMap$Entry

$ java -version
java version "1.8.0_25"
Java(TM) SE Runtime Environment (build 1.8.0_25-b18)
Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)

See also http://discuss.gradle.org/t/using-a-map-in-build-gradle-throws-noclassdeffounderror-ljava-util-hashmap-entry/7325

Using gradle 2.3 to fixes the problem.

the distribution file (zip) for en with help is missing the images folder

IMHO, it is easier to work with the templates when there is a linebreak after aprox 80 characters - not all editors support line wrap...

for:

• versions (with help,without help, with examples etc.)
• formats (docx, pdf, confluence, html etc.)
• supporting tools (i.e. headless EA image export)
• constraints (asciidoc as master format)

provide a gradle build step which exports all diagrams found in an Enterprise Architect project as images with the diagram name as image name

to verify that internal links are ok, images exist etc.

:toc-title: attribute does not work... or I'm misusing it.

Filed an issue with AsciiDoctor-nabble.

Current text in contributors section
/arc42-template/src/DE/asciidoc/snippets/appendix-contributing.adoc
contains an unfinished sentence, it simply stops ...

"Den vielen anonym"

create a gradle build step which converts the subset of adoc which is sued by arc42 into a confluence space.
Target will be the current confluence on demand version (5.3), but goal will be to support as many older versions as possible (let's see what the confluence api will provide us)

let's define some acceptance criteria:
A1: export should look "nice"
A2: if possible, a new export should only add to the confluence history when pages have been changed
A3: images have to be exported

alternatives:

• pandoc
• confluence -> docx-exporter-plugin

schreibe das mal auf deutsch...

gerade sehe ich die mit "ohne Hilfe" versionen. Sollten wir das nicht vielleicht über Styles realisieren?
Ich hatte in meiner Version die Info-Sections im HTML per CSS so konfiguriert, dass sie nur als kleine Bubbles erscheinen, die ausklappen, wenn man mit der Maus drüber fährt.
Im Print-CSS sind sie dann komplett ausgeblendet, sprich, wenn man das HTML-Dokument in ein finales PDF (read-only) wandelt, dann verschwinden die Hilfe-Sektionen automatisch...

Dadurch pflegen wir dann nur noch halb so viele Versionen... ;-)

Feedback willkommen!

shall we have

DE/asciidoc/
.../eap
.../docx
EN/asciidoc/
.../eap
.../docx
´´´
or do we prefer:


    asciidoc/DE/...
    ......./EN/...
    eap/DE...
    .../EN...
    docx/DE/...
    ..../EN/...


I personally opt for the first version :-)
comments welcome

two questions:

1. should we put all sections in a subfolder or keep everything in a flat folder?

2. Asciidoc is able to detect that it is interpreted by github. I would like to add some navigation between the pages in case that it is viewed on github - is this ok? see http://mrhaki.blogspot.de/2014/08/awesome-asciidoc-conditional-directive.html

https://dl.dropbox.com/u/45486/arc42-downloads/template-V6/DE/arc42-template-v60-DE.docx

This document contains many editor hints and modification proposals.

Any idea how we will handle the maintenance of translations? I would sugest to create a branch for each language, just to have a marker which translation is at which version.

...and which translations should we push to this repository? Is there already an "official" english asciidoc version? Should we use the version created by @masch70 (https://github.com/masch70/arc42-template-asciidoc)?