arc42 / arc42-template Goto Github PK
View Code? Open in Web Editor NEWarc42 - the template for software architecture documentation and communication
Home Page: https://arc42.org
License: Other
arc42 - the template for software architecture documentation and communication
Home Page: https://arc42.org
License: Other
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)?
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.
In order to use the template for grails projects withouth asciidoc, a gdoc template is needed. gdoc is a subset of textile...
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
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
Zu dem Dokument hab ich ein paar Anmerkungen:
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
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.
It seems to still work, but some clean ups have been removed
me <- should get more git practice
so that prosective users can immediately start...
(with at least java or maven installed)
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)
Using gradle 2.3 to fixes the problem.
alternatives:
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")
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
Current text in contributors section
/arc42-template/src/DE/asciidoc/snippets/appendix-contributing.adoc
contains an unfinished sentence, it simply stops ...
"Den vielen anonym"
:toc-title: attribute does not work... or I'm misusing it.
Filed an issue with AsciiDoctor-nabble.
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
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?
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...
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.
Konzepte-Themen primär als Checkliste aufnehmen, keine weiteren Erläuterungen mehr.
An image reference in 09_design_decisions.adoc results in a wrong width attribute
would be nice to have a github page with a nice "landing zone" - and maybe forwarding to confluence.arc42.org
to setup an empty asciidoc-based arc42 as simple as possible...
to verify that internal links are ok, images exist etc.
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...)
two questions:
should we put all sections in a subfolder or keep everything in a flat folder?
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
... does not export diagrams which are sub-elements
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?
the build script currently ignores the en-version.
Have to update some parts in order to generate DE and EN versions of the templates
for:
see #33
should be an extra option, not a default
It seems that the build does not work on a *nix OS
we need more documentation for the toolchain itself, all steps of the toolchain and how to use them
create subprojects for
and "master build.gradle"
IMHO, it is easier to work with the templates when there is a linebreak after aprox 80 characters - not all editors support line wrap...
. 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...
so we can generate:
eventually:
3. customized version
...but I guess it only makes sense for the with-help version
let's finish the travis script in order to get deployed templates
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
im Zuge des Buchprojektes "arc42-in-Aktion" haben Peter + ich die Erläuterungen ziemlich aufgeräumt... das mal in einer neuen Version nachziehen...
provide a gradle build step which exports all diagrams found in an Enterprise Architect project as images with the diagram name as image name
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!
as discussed between @rdmueller and myself during JAX-2015
does that sound plausible?
the asciidoc versions of the template shall be copied to our build (= output) directory.
From that, we'll create the download-artifacts one day...
now that the build generates formats and zip files which should include images, the image copy task has to be fixed.
the distribution file (zip) for en with help is missing the images folder
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.