arc42 / faq.arc42.org-site Goto Github PK

format of numbered list is broken

see .../faq/category_f/ for an example:

in principle, sorting works, but:

F-01, F1, F-10 get mixed up...

https://github.com/rdmueller/arc42-faq-site/blob/master/_posts/C-arc42/2016-03-01-q-c-1-3.md

I would add something saying that arc42 is also a documentation - if someone else has to work with the architecture, he will be glad to already have a list of all stakeholder he could approach.

in both docs and faq

A: No, but it would make sense to reference it and distill the architecture requirements from it.
Those architecture requirements should be part of your arc42 documentation.
Some of the overall requirements are unimportant for the architecture, like the color scheme of the application. Others contain hidden architectural decisions. So it is your task to distill these architectonically important requirements and only reference the overall requirements.

Shouldn't we add the C4 approach by simon brown to the building blocks?

C4 = context, containers, components, classes

IMHO, if you are not experienced with the building blocks, this approach is really helpful -
level1 = context
level2 = containers (deployment units like .wars and .jars, filesystems, databases)
level3 = components
level4 = classes

strange behavior - does not occur when "jekyll serve" locally...

an issue with _config.yaml??

despite several experiments, no idea why the build fails with "include file subtle-ads.html not found".

crazy :-)

@gernotstarke Please check if the footer with the "supported by INNOQ"-SVG is okay like this.

Shall I put it on other pages as well like this? On which pages?

Or do you want any changes?

are the keywords ok:

• missing keywords?
• superflous keywords?
• misleading keywords?

or redirect to Home.html...

index.html seems to be required...

Comments on every page - "disqus" is the best-known system:

PRO

• enabling comments without requiring readers to open issue on github.
• slack integration possible
• free to use
• add-free for open-source projects (afaik...)

CON:

• disqus is collecting information about users
• disqus comments are "owned" by disqus (maybe not thaaat bad, as we don't have many comments)

I think we should write something about the difference between SA4D and arc42.

I see the main difference that arc42 need no code and can be used to describe a software architecture independent of code. SA4D builds on the assumption that the needed architecture diagrams can be extracted from the code - it does not plan the architecture, but documents it.

As a result, both approaches might be used together: arc42 for planning and SA4D in a later stage for checking that reality and plans are the same. From that point on, SA4D could generate the diagrams for arc42.

Please correct me if I got it wrong...

analog docs...

simply add "®" to the product names.

oops - this is a css issue...

to reproduce: make browser window (much!) smaller...

proposal:

[ ] remove submodule
[ ] commit & push version without submodule
[ ] re-include submodule with branch "main" instead of master

although I see them in local preview...

disqus comments are currently missing ...

explain how to approach documentation of existing systems

need to find a simple way to cross-reference, both locally and on the "real" website!

maybe redirect from index.html to "Home.md" page...

so we have stable targets for hyperlinks...

reason: the arc42.org is statically generated and the mail-server has to be "manually" maintained...

For higher automation, this should be removed (in all three sites) and replaced by [email protected]

for people without disqus-account - add a small contact form.

Idea: https://formspree.io/

summarize slack discussion with @rdmueller