vault backup: 2026-01-05 13:03:55
This commit is contained in:
windyboy
@@ -0,0 +1,3 @@
|
||||
- **Areas are ==**personal**==** to you, Resources are ==**generally useful for others**==
|
||||
- Just move the note in the right place do not file them or change them
|
||||
- You can always split notebook if they become too big
|
||||
@@ -0,0 +1,2 @@
|
||||
- Let's make it fun and it's going to be easier too
|
||||
- ==If you don't have at least one new project or one archived project or one split/merge project in a week you need to question the size of them==
|
||||
@@ -0,0 +1 @@
|
||||
According to biographer Claire Tomalin, Dickens crafted much of the tale in his head while engaged in nighttime walks that covered 15 to 20 miles. As a result of this ambulatory cogitation, the entire story took only six weeks to complete in the late fall of 1843.
|
||||
@@ -0,0 +1,2 @@
|
||||
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
List:
|
||||
- New application features and menu
|
||||
- Focus mode for the current line
|
||||
- Focus UI for writing
|
||||
@@ -0,0 +1,365 @@
|
||||
/* Special Font */
|
||||
body, p {
|
||||
font-family: "Dank Mono",'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Microsoft YaHei Light", sans-serif;
|
||||
}
|
||||
|
||||
.cm-s-obsidian {
|
||||
font-family: "Dank Mono",'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Microsoft YaHei Light", sans-serif;
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
.editor {
|
||||
font-family: "Dank Mono",'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Microsoft YaHei Light", sans-serif;
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
.markdown-preview-view code {
|
||||
font-family: "Dank Mono",'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Microsoft YaHei Light", sans-serif;
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
.preview {
|
||||
font-family: "Dank Mono",'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Microsoft YaHei Light", sans-serif;
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
/* Scrollbar */
|
||||
::-webkit-scrollbar {
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
/**/
|
||||
/* Editor Section */
|
||||
/**/
|
||||
/* Line size */
|
||||
.cm-s-obsidian pre.HyperMD-header {
|
||||
line-height: 1!important;
|
||||
}
|
||||
|
||||
/* Selection */
|
||||
.theme-light {
|
||||
--text-selection: rgba(112, 93, 207, 0.5);
|
||||
}
|
||||
|
||||
.theme-dark {
|
||||
--text-selection: rgba(112, 93, 207, 0.5);
|
||||
}
|
||||
|
||||
::selection {
|
||||
background-color: #705dcf;
|
||||
color: white;
|
||||
}
|
||||
|
||||
/* Title */
|
||||
/* Current main pane */
|
||||
.view-header-title {
|
||||
color: #705dcf;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.workspace-leaf.mod-active .view-header {
|
||||
text-align: center;
|
||||
}
|
||||
/* Other pane */
|
||||
.workspace-leaf-header-title-container {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
/* Headers */
|
||||
span.cm-formatting.cm-formatting-header.cm-formatting-header-1.cm-header.cm-header-1 {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
span.cm-formatting.cm-formatting-header.cm-formatting-header-2.cm-header.cm-header-2 {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
span.cm-formatting.cm-formatting-header.cm-formatting-header-3.cm-header.cm-header-3 {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
span.cm-formatting.cm-formatting-header.cm-formatting-header-4.cm-header.cm-header-4 {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
span.cm-formatting.cm-formatting-header.cm-formatting-header-5.cm-header.cm-header-5 {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
span.cm-formatting.cm-formatting-header.cm-formatting-header-6.cm-header.cm-header-6 {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
/* Header folder icon */
|
||||
.CodeMirror-foldgutter-open, .CodeMirror-foldgutter-folded {
|
||||
color: #3e3471;
|
||||
}
|
||||
|
||||
.CodeMirror-foldgutter-open, .CodeMirror-foldgutter-folded {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
/* Cursor */
|
||||
.cm-fat-cursor .CodeMirror-cursor {
|
||||
background: #3e3471;
|
||||
}
|
||||
|
||||
.cm-animate-fat-cursor {
|
||||
background-color: #3e3471;
|
||||
}
|
||||
|
||||
/* Selection in popup ([[]] autocomplete)*/
|
||||
.suggestion-item.is-selected {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.theme-light .suggestion-shortcut {
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
/* Inner and Outer links */
|
||||
.cm-url {
|
||||
color: lightblue!important;
|
||||
}
|
||||
|
||||
.markdown-highlighting .internal-link .cl-underlined-text {
|
||||
color: var(--text-accent)!important;
|
||||
}
|
||||
|
||||
.markdown-highlighting .link .cl-underlined-text {
|
||||
color: lightblue!important;
|
||||
}
|
||||
|
||||
/* Blockquote */
|
||||
.preview blockquote {
|
||||
background-color: var(--background-modifier-border);
|
||||
border: 1px solid var(--text-muted);
|
||||
}
|
||||
|
||||
/* Highlights and Bold */
|
||||
strong {
|
||||
font-size: larger;
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
mark {
|
||||
background-color: darkgoldenrod;
|
||||
}
|
||||
|
||||
.markdown-highlighting .tag {
|
||||
color: var(--text-accent)!important;
|
||||
}
|
||||
|
||||
/* Tables */
|
||||
.markdown-preview-view th {
|
||||
background-color: #3e3471;
|
||||
color: white
|
||||
}
|
||||
|
||||
.cm-s-obsidian pre.HyperMD-table-row span.cm-hmd-table-sep {
|
||||
color: unset;
|
||||
}
|
||||
|
||||
.cm-s-obsidian pre.HyperMD-table-row-1 > span {
|
||||
color: unset;
|
||||
}
|
||||
|
||||
/* Status bar */
|
||||
.theme-dark .status-bar-item {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.theme-light .status-bar-item {
|
||||
color: black;
|
||||
}
|
||||
|
||||
/**/
|
||||
/* Preview section */
|
||||
/**/
|
||||
/* Centered preview */
|
||||
.markdown-preview-view
|
||||
{
|
||||
padding-left: 10% !important;
|
||||
padding-right: 10% !important;
|
||||
}
|
||||
|
||||
.markdown-embed-title {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
.markdown-preview-view .markdown-embed {
|
||||
background-color: var(--background-primary-alt);
|
||||
margin-top: 0.5rem;
|
||||
margin-bottom: 0.5rem;
|
||||
}
|
||||
|
||||
.markdown-preview-view .internal-link {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
.markdown-preview-view a {
|
||||
color: lightblue;
|
||||
}
|
||||
|
||||
/**/
|
||||
/* Side panel section */
|
||||
/**/
|
||||
/* Plugin Title and Description */
|
||||
.plugin-name {
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
.plugin-description {
|
||||
color: var(--text-normal)
|
||||
}
|
||||
|
||||
/* Files title and Buttons */
|
||||
.nav-file-title-content, .nav-folder-title-content {
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
.nav-action-button {
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
/* File explorer navigation selection */
|
||||
.nav-file.is-active > .nav-file-title, .nav-file.is-active > .nav-folder-title, .nav-file.is-active > .nav-folder-collapse-indicator, .nav-folder.is-active > .nav-file-title, .nav-folder.is-active > .nav-folder-title, .nav-folder.is-active > .nav-folder-collapse-indicator {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
body:not(.is-grabbing) .nav-file-title:hover, body:not(.is-grabbing) .nav-folder-title:hover {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.nav-file-title-content, .nav-folder-title-content {
|
||||
color:unset;
|
||||
}
|
||||
|
||||
.nav-folder.mod-root > .nav-file-title:hover, .nav-folder.mod-root > .nav-folder-title:hover {
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
body:not(.is-grabbing) .nav-file-title:hover .nav-folder-collapse-indicator, body:not(.is-grabbing) .nav-folder-title:hover .nav-folder-collapse-indicator {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.nav-file-title, .nav-folder-title, .nav-folder-collapse-indicator {
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
/* File explorer menu*/
|
||||
.menu-item:hover {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
/* Backlinks Color and Text */
|
||||
.search-result-file-matched-text {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.search-result-file-title {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
.search-result-file-matches {
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
.search-result-file-title:hover {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.search-result-file-match:hover {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
/* Folder arrow */
|
||||
.nav-folder.is-collapsed .nav-folder-collapse-indicator {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
.nav-folder-collapse-indicator {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
/* Tag Selection */
|
||||
.tag-pane-tag:hover {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.theme-light .tag-pane-tag-count {
|
||||
color: var(--text-normal)
|
||||
}
|
||||
|
||||
/* Title */
|
||||
.side-dock-title {
|
||||
color: #705dcf;
|
||||
}
|
||||
|
||||
/* Ribon */
|
||||
.side-dock-ribbon {
|
||||
background-color: #3e3471!important;
|
||||
color: var(--text-muted)
|
||||
}
|
||||
|
||||
.side-dock-ribbon-tab, .side-dock-ribbon-action {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.theme-dark .side-dock-ribbon-tab.is-active {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.theme-dark .side-dock-ribbon-tab.is-before-active {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.theme-light .side-dock-ribbon-tab.is-active {
|
||||
color: var(--text-normal);
|
||||
}
|
||||
|
||||
.theme-light .side-dock-ribbon-tab.is-before-active {
|
||||
color: white;
|
||||
}
|
||||
|
||||
.side-dock-ribbon-tab-inner {
|
||||
color: unset;
|
||||
}
|
||||
|
||||
.side-dock-ribbon-before.is-before-active .side-dock-ribbon-tab-inner, .side-dock-ribbon-after.is-after-active .side-dock-ribbon-tab-inner, .side-dock-ribbon-tab.is-before-active .side-dock-ribbon-tab-inner, .side-dock-ribbon-tab.is-after-active .side-dock-ribbon-tab-inner {
|
||||
background-color: #3e3471;
|
||||
}
|
||||
|
||||
.side-dock-ribbon-tab, .side-dock-ribbon-before, .side-dock-ribbon-after, .side-dock-ribbon-tab-inner {
|
||||
transition: none;
|
||||
}
|
||||
|
||||
/**/
|
||||
/* Settings panel Section */
|
||||
/**/
|
||||
.vertical-tab-nav-item.is-active {
|
||||
background-color: #3e3471;
|
||||
color:white;
|
||||
}
|
||||
|
||||
.horizontal-tab-nav-item:hover, .vertical-tab-nav-item:hover {
|
||||
background-color: #3e3471;
|
||||
color: white;
|
||||
}
|
||||
|
||||
.vertical-tab-nav-item.is-active {
|
||||
background-color: #3e3471;
|
||||
}
|
||||
|
||||
.vertical-tab-nav-item.is-active {
|
||||
border-left-color: #3e3471;
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
- areas are usually the overhead in the background (maintenance, support, upgrade etc)
|
||||
- projects are finite and clean they have a concrete outcome/package/deliverable
|
||||
- areas and resources can be more aspirational and dreams mostly things you want to start to take notes on interest are like plane on your radar they come and go and come back later
|
||||
@@ -0,0 +1,44 @@
|
||||
|
||||
## P.A.R.A
|
||||
P.rojects
|
||||
A.reas
|
||||
R.esources
|
||||
A.rchive
|
||||
|
||||
## Definitions
|
||||
- Projects => Every current projects (see def. below) that are actionable with their notes, files, artifacts
|
||||
- Areas => Zone of responsibility with standard to uphold over long periods, parent, animals, management, coding, house
|
||||
- Resources => Zone of interest for various topics that don’t require standard/responsibility, game, phone, productivity, self development, technology
|
||||
- Archive => Where things from all the other category become unused, finished, change of responsibility etc
|
||||
|
||||
A project is something with a goal and a deadline that requires more than 1 step to complete
|
||||
A project packet is an intermediate step before the completion that is itself a “thing” made and that could be reused or serves as a snapshot of progress
|
||||
|
||||
## Workflow
|
||||
### Projects flow
|
||||
Project -> Areas -> Resources -> Archive
|
||||
|
||||
Project -> AreasA project turned into something more after finishing it. Eg. new responsibility over the thing made, new job opportunity etc
|
||||
Project -> ResourcesA part of the project packet or the thing made could be reused in other ways later. Eg. PowerPoint layout, book resume, study notes etc
|
||||
Project -> ArchiveOnce the project is finished, areas and resources information or packet have been moved what’s left goes into archive for conservation and possible reuse later
|
||||
|
||||
### Areas flow
|
||||
Project <- Areas -> Resources -> Archive
|
||||
|
||||
Areas -> Project
|
||||
Areas -> Resources
|
||||
Areas -> Archive
|
||||
|
||||
### Resources flow
|
||||
Project <- Areas <- Resources -> Archive
|
||||
|
||||
Resources -> Project
|
||||
Resources -> Areas
|
||||
Resources -> Archive
|
||||
|
||||
### Archive flow
|
||||
Project <- Areas <- Resources <- Archive
|
||||
|
||||
Archive -> Project
|
||||
Archive -> Areas
|
||||
Archive -> Resources
|
||||
@@ -0,0 +1,41 @@
|
||||
# The Methodology
|
||||
The P.A.R.A system is surprisingly simple at first glance but very powerful when applied. At its core, it's just a four folder wide hierarchy with four-layer deeps, starting with those four root folders:
|
||||
|
||||
1. Projects
|
||||
2. Areas
|
||||
3. Resources
|
||||
4. Archive
|
||||
|
||||
From there, each of the roots is allowed one sub-folder level and then notes. That's how the four levels deep work: App (1) -> `1. Projects` (2) -> P.A.R.A. Demo Vault (3) -> Methodology (4). The reason for this is to keep it manageable and easy to remember and navigate. That restriction was initially because of Evernote limitation, but it turns out to have some serendipity potential. By putting all your notes from similar "zone" and actionability together, you end up with many serendipitous findings of new related notes and ideas.
|
||||
|
||||
Just those root folders and their children, the system can contain everything most people needs for their notes and files. This taxonomy works because you don't split things based on categories but actionability and areas of your life. So now, let's define those roots to help see how it works.
|
||||
|
||||
## Definition
|
||||
1. Projects: *Every current project that is actionable with its notes, files, artifacts*
|
||||
- If you have a project that requires notes or files, it should have a folder in 1. Projects.
|
||||
- Since this folder is for projects you are working on _right now_, it's the most actionable and probably where you will spend most of your time.
|
||||
2. Areas: *Zone of responsibility with standard to uphold over long periods*, parent, animals, management, coding, house.
|
||||
- Areas are **the personal** bucket of your life for important things that don't have an end date. You won't ever "stop" working on your health; for example, it's a constant ongoing thing.
|
||||
- While areas can (and often do) generate projects, they are not linked since it's already intuitive which areas a project comes from, so there's no need to create an explicit link between, for example, the "Server maintenance" project and the "Sysadmin" area.
|
||||
- Finally, because they are personal, areas contain information you wrote for _yourself only_ about those areas in your life. Which is opposite to 3. Resources.
|
||||
3. Resources: *Zone of interest for various topics that don't require standard/responsibility*, game, cooking, productivity, technology.
|
||||
- Resources are **generally helpful for others**, not just you. For example, if someone was to ask you for information about cooking, you could zip that folder and send it to them.
|
||||
- The folders in there will very often reflect your various interests, what you're curious about and want to learn more about.
|
||||
- They are not necessarily actual "resources" as in PDF, Pictures, etc. they can also be notes about those subjects
|
||||
4. Archives: *Where stuff from all the other category become unused*, finished project, change of responsibility, etc.
|
||||
- This folder will be where you put things you won't need for a while, as the name suggests. For the most part, something in there won't be seen for a time, and that's why it has the lowest actionability, but sometimes a new project could use things in there, or a change of areas might mean you need to get stuff out of there.
|
||||
- For example, you have lots of notes on living with a pet in a small apartment, and then you move to a new bigger one. You could move all those to the archive if one day you have to go back to a small apartment again take them out.
|
||||
|
||||
## Setup
|
||||
The setup for it is pretty simple, create root folders for each category, like in this sandbox. From there, move all of your current notes into `4. Archives` as is with the same existing hierarchy (remember it's not deleted 😉). Then create one folder for each of your current projects you're working on in `1. Projects` (remember only one sub-folder to stay four levels deep). For `2. Areas`, if you already know some of them, you can create the folders already, but try not to have too many empty folders. Finally, `3. Resources`, you want to stay empty for now unless you already captured things that could go in it. The idea is that each time you go into `4. Archives` to take one of the "old" notes or files, you then move it to the right spot in the new taxonomy. Doing it this way will highlight the most used notes, and what's left behind can stay in Archive until it's finally used (or not).
|
||||
|
||||
Once you have the folder hierarchy done, you want to copy it across all your other systems; that is where P.A.R.A. starts to shine. You want to have the same hierarchy for your local files on your computer, in your notes, in your Dropbox/Google Drive/iCloud, and everywhere else you have to keep information. Doing that will make it very quick and easy to find things you might need for work or something in the same zone across all your apps. For this reason, the more system you integrate the taxonomy into, the easier finding things will be.
|
||||
|
||||
### Setup tips:
|
||||
- If a note (or a file) can go into two different folders, you put it in the folder where you will **_most likely need it next_** since folders are based on actionability, and it will get moved anyway in the flow of things.
|
||||
- You can also have the "same" folder in 2 different roots. For example, `2. Areas/Health` and `3. Resources/Health` the first one is **_your_** health notes and the other **general** health-related notes.
|
||||
- Remember, you do **_not_** want to sort all your current notes and files and put them in the new folder, put them all in the Archive as is, and then move them out as you use them.
|
||||
- You do **_not_** have to do every single folder for your local files and cloud service; create the sub-folders are you need them, **_but_** you need to have one complete setup, most likely in your notes, to act as the primary reference for the others.
|
||||
|
||||
|
||||
# Next stop [[Workflows]]
|
||||
@@ -0,0 +1,22 @@
|
||||
## Start here
|
||||
- General how-this-work
|
||||
- What to expect
|
||||
- How to start
|
||||
## Definition
|
||||
- Projects: Short-term efforts with a clear outcome
|
||||
- Areas: Long-term responsibilities to maintain
|
||||
- Resources: Topics or interests useful in the future
|
||||
- Archives: Inactive items from other categories
|
||||
## Methodology
|
||||
- Actionnability
|
||||
- Fluidity
|
||||
- Project based
|
||||
- Constraint
|
||||
## Workflow
|
||||
- Capture: Collect everything in Inbox
|
||||
- Clarify: Determine if it's a Project, Area, Resource, or Archive
|
||||
- Organize: Move to appropriate PARA folder
|
||||
- Review: Regular reviews to maintain system
|
||||
## Next steps
|
||||
- Tiago's blog
|
||||
- Discord
|
||||
@@ -0,0 +1,39 @@
|
||||
# PKM Content Organization - Decision Note
|
||||
|
||||
## Analysis (2025-12-29)
|
||||
|
||||
After reviewing both locations containing PARA methodology content:
|
||||
- **[300-resources/Personal Knowledge Management](300-resources/Personal Knowledge Management)** - 8 files (course notes, references, essays)
|
||||
- **[100-project/Personal/PKM/PARA](100-project/Personal/PKM/PARA)** - 3 files (implementation guide)
|
||||
|
||||
## Decision: Keep Current Structure
|
||||
|
||||
**Rationale:**
|
||||
1. **Different purposes, complementary content:**
|
||||
- `300-resources/PKM/` contains **source material** from BASB courses, external essays, and learning references
|
||||
- `100-project/PKM/PARA/` contains **implementation documentation** specific to this vault's setup
|
||||
|
||||
2. **PARA principle alignment:**
|
||||
- Resources = generally useful reference material (course notes, methodology explanations)
|
||||
- Projects = active work on implementing/customizing the system
|
||||
|
||||
3. **Content breakdown:**
|
||||
- **300-resources/PKM/** (Reference material):
|
||||
- BASB Class 7 & 8 notes (course content)
|
||||
- PARA Notes.md & PARA Notes from class.md (methodology reference)
|
||||
- Gregory Gundersen essay (writing philosophy)
|
||||
- Dickens deep work (anecdote)
|
||||
- Images.md (visual references)
|
||||
|
||||
- **100-project/PKM/PARA/** (Implementation):
|
||||
- Methodology.md (how to apply in Obsidian)
|
||||
- Workflows.md (practical examples for this vault)
|
||||
- Outline.md (project plan)
|
||||
|
||||
## Cleanup Actions Taken
|
||||
|
||||
✅ Moved arc42 from `300-resources/PKM/` to `300-resources/Development/Architecture/` (was misplaced)
|
||||
|
||||
## Recommendation
|
||||
|
||||
No merge needed. The two locations serve distinct purposes and should remain separate. If PKM project becomes inactive, move implementation docs to `200-area/Personal Development/` (ongoing learning responsibility) and keep course references in `300-resources/`.
|
||||
@@ -0,0 +1,25 @@
|
||||
# How to use this for work
|
||||
The workflow of P.A.R.A. is based on projects, as they are the most actionable information, but the information also flows in other ways. Most of the flowing and moving in the system will happen when you use the notes or when you are done with a project; that's why starting and finishing projects are crucial moments. As notes can flow to/from each part of the P.A.R.A, it's best to show with examples:
|
||||
|
||||
## Example 1 - Project
|
||||
This example is the "normal" workflow for most things. First, you start with a project, something like writing this starter kit.
|
||||
|
||||
You first create the folder for the project once you're ready. Then you go around `2. Areas` and `3. Resources` to find the information possibly useful for the project; in this case, I would look in my `Second Brain` folder and my `Personal Knowledge Management` folder. From there starts the first flow, you take those notes, pictures, etc., and put them in the folder. At this point, you use them to create the product and complete the project.
|
||||
|
||||
Once the project is over, the 2nd flow can start; it's time to look at all the notes and artifacts you created and used. For each of them, see if they would still be helpful later if they could be turned into a template or formatted more generically. The idea is to keep those around for use in other projects later, so put them in the correct `2. Areas` folder. The remainder goes into `4. Archives`.
|
||||
|
||||
## Example 2 - Areas change
|
||||
You decided to change your job and launch your own business in a completely different field. That would mean most of the information in your job-related `2. Areas` would not be actionable anymore. So now you can look if some things in that area could still be helpful and move the rest to `4. Archives`.
|
||||
|
||||
If a couple of months later something comes up and it forces you to get back into that first field, take the folder out of `4. Archives` and put it back into `2. Areas`, and you're back into business just like before.
|
||||
|
||||
## Example 3 - Resource change
|
||||
Since things in `3. Resources` interest you to learn more about it can be that it changes at some point. A resource folder on `Marketing`, for example, could turn into a freelance job in marketing.
|
||||
|
||||
When that happens, you now have a standard to uphold (freelance standard), so you create a new folder in `2. Areas` for "Marketing" and move all the notes you wrote yourself from `3. Resources` into that new one (since `2. Areas` is for things you wrote yourself)
|
||||
|
||||
|
||||
# Next step Explore!
|
||||
You're officially done with the explanation now; you can proceed to try it for yourself or explore more around. If you have questions, don't hesitate to ask on the forum thread or read the [P.A.R.A. complete article](https://fortelabs.co/blog/para/) for a deeper dive into all the details.
|
||||
|
||||
If you want to look at more demo vaults like this, I also have my own system, a fork of P.A.R.A. for my use over [here](https://forum.obsidian.md/t/paan-starter-kit/21782). Finally, for more general writing, I have my blog where I will often write about that system or others at [maximecote.me](https://maximecote.me/)
|
||||
@@ -0,0 +1,5 @@
|
||||
### Notes
|
||||
```dataview
|
||||
table file.ctime as Date from "300-resources/Personal Knowledge Management"
|
||||
sort file.name
|
||||
```
|
||||
+53
@@ -0,0 +1,53 @@
|
||||
http://gregorygundersen.com/blog/2020/01/12/why-research-blog/
|
||||
|
||||
Before I started taking writing seriously, I had a loose grasp of many mathematical and technical concepts; and I was not sure how to tackle open-ended problem
|
||||
|
||||
I learned very early the difference between knowing the name of something and knowing something.
|
||||
|
||||
When I write a blog post, I imagine my supervisor, a respected
|
||||
colleague, or a future employer reading my explanation. These imagined readers force me to ask myself honestly if I understand what I am writing.
|
||||
|
||||
The end result is that writing forces me to acknowledge and then work through my confusion.
|
||||
|
||||
Summarizing a paper in your own words restructures the content to focus on learning rather than novelty.
|
||||
|
||||
A side effect of having written detailed technical notes is that I
|
||||
calibrate my confidence on a topic. If I now understand something, I am sure of it and can explain myself clearly. If I don't understand something, I have a sense of why it is difficult to understand or what prerequisite knowledge I am missing.
|
||||
|
||||
For me, writing things down is the best way I have found to ensure that I actually do the work.
|
||||
|
||||
Blogging has taught me how to read a paper because explaining something is a more active form of understanding
|
||||
|
||||
This process mimics the act of presenting and is great practice for it.
|
||||
|
||||
However, with proficiency came creativity. Programming became less important than what I was building and why. When I started my PhD, I hypothesized that the same rules would apply: I wouldn't be able to think creatively about machine learning until I built up the requisite knowledge base. In programming, you can practice by writing programs; but how can you practice research? For me, writing detailed, expository technical notes is the equivalent of the programmer's side project: it forces me to intentionally and systematically build my knowledge base by understanding ideas, working through proofs, and implementing models.
|
||||
|
||||
My understanding and confidence in the material changed profoundly. I became intellectually committed in a way that was impossible without first understanding the problem
|
||||
|
||||
Under pressure, my mind, like a cart on a well-worn path, finds the same old ruts. Once again, writing breaks this cycle because it requires more active participation.
|
||||
|
||||
Hard problems are intimidating; and I often do not know where to start and am worried that I will waste my time. Writing blog posts about the larger context of a problem is my way of flanking it, of head faking myself about what I am actually doing. This lowers the psychological stakes because, rather than directly attacking the problem, I am producing something that I know will be valuable either way.
|
||||
|
||||
These posts, written in the spring and summer, allowed me to start thinking about and preparing for the problem indirectly.
|
||||
|
||||
However, writing is my other way of mitigating risk. If my current
|
||||
project were to fail, the directed and intentional process of
|
||||
systematically attacking the background material will have prepared me well for the next problem.
|
||||
|
||||
If you don't see that what you are working on is almost obvious, then you are not ready to work on that yet.
|
||||
|
||||
I find this quote comforting because it suggests that good ideas---at least for one famous mathematician---do not come into the mind ex niliho. Rather, good ideas come from so deeply understanding a problem that the solution seems obvious.
|
||||
|
||||
In my own experience, writing has gotten me closer than anything else to having original research thoughts that feel obvious.
|
||||
|
||||
By understanding problems deeply, you increase the probability that you can work on an important, attackable problem.
|
||||
|
||||
I think of writing-as-learning as database indexing. In a database, an index is a data structure that efficiently keeps track of where rows in a table are located. To insert into a database via an index is slower than simply adding the row to the bottom of the table because the database must do some bookkeeping. However, querying a database is extremely efficient. A layperson's example is organizing your books alphabetically.
|
||||
|
||||
Importantly, I had forgotten if the relationship were true, but it felt correct, and I knew exactly where to look to confirm my guess.
|
||||
|
||||
Maybe one thing I appreciate more now is that the state of human knowledge is full of holes. When you're young you have the impression that almost everything is known, but now I have this feeling that almost everything is unknown about mathematics. There are these very thin channels that people have gone along, like ants following each other along a trail. You find these long thin trails of things, and most things are undeveloped. I have more of a sense of the openness of it.
|
||||
|
||||
In short, mathematics only exists in a living community of
|
||||
mathematicians that spreads understanding and breaths life into ideas both old and new. The real satisfaction from mathematics is in learning from others and sharing with others. All of us have clear understanding of a few things and murky concepts of many more. There is no way to run out of ideas in need of clarification. The question of who is the first person to ever set foot on some square meter of land is really secondary. Revolutionary change does matter, but revolutions are few,
|
||||
and they are not self-sustaining --- they depend very heavily on the community of mathematicians.
|
||||
@@ -0,0 +1,989 @@
|
||||
#
|
||||
|
||||
**About arc42**
|
||||
|
||||
arc42, the template for documentation of software and system
|
||||
architecture.
|
||||
|
||||
Template Version 8.2 EN. (based upon AsciiDoc version), January 2023
|
||||
|
||||
Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and
|
||||
contributors. See <https://arc42.org>.
|
||||
|
||||
::: note
|
||||
This version of the template contains some help and explanations. It is
|
||||
used for familiarization with arc42 and the understanding of the
|
||||
concepts. For documentation of your own system you use better the
|
||||
*plain* version.
|
||||
:::
|
||||
|
||||
# Introduction and Goals {#section-introduction-and-goals}
|
||||
|
||||
Describes the relevant requirements and the driving forces that software
|
||||
architects and development team must consider. These include
|
||||
|
||||
- underlying business goals,
|
||||
|
||||
- essential features,
|
||||
|
||||
- essential functional requirements,
|
||||
|
||||
- quality goals for the architecture and
|
||||
|
||||
- relevant stakeholders and their expectations
|
||||
|
||||
## Requirements Overview {#_requirements_overview}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
Short description of the functional requirements, driving forces,
|
||||
extract (or abstract) of requirements. Link to (hopefully existing)
|
||||
requirements documents (with version number and information where to
|
||||
find it).
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
From the point of view of the end users a system is created or modified
|
||||
to improve support of a business activity and/or improve the quality.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
Short textual description, probably in tabular use-case format. If
|
||||
requirements documents exist this overview should refer to these
|
||||
documents.
|
||||
|
||||
Keep these excerpts as short as possible. Balance readability of this
|
||||
document with potential redundancy w.r.t to requirements documents.
|
||||
|
||||
See [Introduction and Goals](https://docs.arc42.org/section-1/) in the
|
||||
arc42 documentation.
|
||||
|
||||
## Quality Goals {#_quality_goals}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
The top three (max five) quality goals for the architecture whose
|
||||
fulfillment is of highest importance to the major stakeholders. We
|
||||
really mean quality goals for the architecture. Don't confuse them with
|
||||
project goals. They are not necessarily identical.
|
||||
|
||||
Consider this overview of potential topics (based upon the ISO 25010
|
||||
standard):
|
||||
|
||||
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
You should know the quality goals of your most important stakeholders,
|
||||
since they will influence fundamental architectural decisions. Make sure
|
||||
to be very concrete about these qualities, avoid buzzwords. If you as an
|
||||
architect do not know how the quality of your work will be judged...
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
A table with quality goals and concrete scenarios, ordered by priorities
|
||||
|
||||
## Stakeholders {#_stakeholders}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
Explicit overview of stakeholders of the system, i.e. all person, roles
|
||||
or organizations that
|
||||
|
||||
- should know the architecture
|
||||
|
||||
- have to be convinced of the architecture
|
||||
|
||||
- have to work with the architecture or with code
|
||||
|
||||
- need the documentation of the architecture for their work
|
||||
|
||||
- have to come up with decisions about the system or its development
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
You should know all parties involved in development of the system or
|
||||
affected by the system. Otherwise, you may get nasty surprises later in
|
||||
the development process. These stakeholders determine the extent and the
|
||||
level of detail of your work and its results.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
Table with role names, person names, and their expectations with respect
|
||||
to the architecture and its documentation.
|
||||
|
||||
+-------------+---------------------------+---------------------------+
|
||||
| Role/Name | Contact | Expectations |
|
||||
+=============+===========================+===========================+
|
||||
| *\<Role-1>* | *\<Contact-1>* | *\<Expectation-1>* |
|
||||
+-------------+---------------------------+---------------------------+
|
||||
| *\<Role-2>* | *\<Contact-2>* | *\<Expectation-2>* |
|
||||
+-------------+---------------------------+---------------------------+
|
||||
|
||||
# Architecture Constraints {#section-architecture-constraints}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
Any requirement that constraints software architects in their freedom of
|
||||
design and implementation decisions or decision about the development
|
||||
process. These constraints sometimes go beyond individual systems and
|
||||
are valid for whole organizations and companies.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
Architects should know exactly where they are free in their design
|
||||
decisions and where they must adhere to constraints. Constraints must
|
||||
always be dealt with; they may be negotiable, though.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
Simple tables of constraints with explanations. If needed you can
|
||||
subdivide them into technical constraints, organizational and political
|
||||
constraints and conventions (e.g. programming or versioning guidelines,
|
||||
documentation or naming conventions)
|
||||
|
||||
See [Architecture Constraints](https://docs.arc42.org/section-2/) in the
|
||||
arc42 documentation.
|
||||
|
||||
# System Scope and Context {#section-system-scope-and-context}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
System scope and context - as the name suggests - delimits your system
|
||||
(i.e. your scope) from all its communication partners (neighboring
|
||||
systems and users, i.e. the context of your system). It thereby
|
||||
specifies the external interfaces.
|
||||
|
||||
If necessary, differentiate the business context (domain specific inputs
|
||||
and outputs) from the technical context (channels, protocols, hardware).
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
The domain interfaces and technical interfaces to communication partners
|
||||
are among your system's most critical aspects. Make sure that you
|
||||
completely understand them.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
Various options:
|
||||
|
||||
- Context diagrams
|
||||
|
||||
- Lists of communication partners and their interfaces.
|
||||
|
||||
See [Context and Scope](https://docs.arc42.org/section-3/) in the arc42
|
||||
documentation.
|
||||
|
||||
## Business Context {#_business_context}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
Specification of **all** communication partners (users, IT-systems, ...)
|
||||
with explanations of domain specific inputs and outputs or interfaces.
|
||||
Optionally you can add domain specific formats or communication
|
||||
protocols.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
All stakeholders should understand which data are exchanged with the
|
||||
environment of the system.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
All kinds of diagrams that show the system as a black box and specify
|
||||
the domain interfaces to communication partners.
|
||||
|
||||
Alternatively (or additionally) you can use a table. The title of the
|
||||
table is the name of your system, the three columns contain the name of
|
||||
the communication partner, the inputs, and the outputs.
|
||||
|
||||
**\<Diagram or Table>**
|
||||
|
||||
**\<optionally: Explanation of external domain interfaces>**
|
||||
|
||||
## Technical Context {#_technical_context}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
Technical interfaces (channels and transmission media) linking your
|
||||
system to its environment. In addition a mapping of domain specific
|
||||
input/output to the channels, i.e. an explanation which I/O uses which
|
||||
channel.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
Many stakeholders make architectural decision based on the technical
|
||||
interfaces between the system and its context. Especially infrastructure
|
||||
or hardware designers decide these technical interfaces.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
E.g. UML deployment diagram describing channels to neighboring systems,
|
||||
together with a mapping table showing the relationships between channels
|
||||
and input/output.
|
||||
|
||||
**\<Diagram or Table>**
|
||||
|
||||
**\<optionally: Explanation of technical interfaces>**
|
||||
|
||||
**\<Mapping Input/Output to Channels>**
|
||||
|
||||
# Solution Strategy {#section-solution-strategy}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
A short summary and explanation of the fundamental decisions and
|
||||
solution strategies, that shape system architecture. It includes
|
||||
|
||||
- technology decisions
|
||||
|
||||
- decisions about the top-level decomposition of the system, e.g.
|
||||
usage of an architectural pattern or design pattern
|
||||
|
||||
- decisions on how to achieve key quality goals
|
||||
|
||||
- relevant organizational decisions, e.g. selecting a development
|
||||
process or delegating certain tasks to third parties.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
These decisions form the cornerstones for your architecture. They are
|
||||
the foundation for many other detailed decisions or implementation
|
||||
rules.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
Keep the explanations of such key decisions short.
|
||||
|
||||
Motivate what was decided and why it was decided that way, based upon
|
||||
problem statement, quality goals and key constraints. Refer to details
|
||||
in the following sections.
|
||||
|
||||
See [Solution Strategy](https://docs.arc42.org/section-4/) in the arc42
|
||||
documentation.
|
||||
|
||||
# Building Block View {#section-building-block-view}
|
||||
|
||||
::: formalpara-title
|
||||
**Content**
|
||||
:::
|
||||
|
||||
The building block view shows the static decomposition of the system
|
||||
into building blocks (modules, components, subsystems, classes,
|
||||
interfaces, packages, libraries, frameworks, layers, partitions, tiers,
|
||||
functions, macros, operations, data structures, ...) as well as their
|
||||
dependencies (relationships, associations, ...)
|
||||
|
||||
This view is mandatory for every architecture documentation. In analogy
|
||||
to a house this is the *floor plan*.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
Maintain an overview of your source code by making its structure
|
||||
understandable through abstraction.
|
||||
|
||||
This allows you to communicate with your stakeholder on an abstract
|
||||
level without disclosing implementation details.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
The building block view is a hierarchical collection of black boxes and
|
||||
white boxes (see figure below) and their descriptions.
|
||||
|
||||
|
||||
|
||||
**Level 1** is the white box description of the overall system together
|
||||
with black box descriptions of all contained building blocks.
|
||||
|
||||
**Level 2** zooms into some building blocks of level 1. Thus it contains
|
||||
the white box description of selected building blocks of level 1,
|
||||
together with black box descriptions of their internal building blocks.
|
||||
|
||||
**Level 3** zooms into selected building blocks of level 2, and so on.
|
||||
|
||||
See [Building Block View](https://docs.arc42.org/section-5/) in the
|
||||
arc42 documentation.
|
||||
|
||||
## Whitebox Overall System {#_whitebox_overall_system}
|
||||
|
||||
Here you describe the decomposition of the overall system using the
|
||||
following white box template. It contains
|
||||
|
||||
- an overview diagram
|
||||
|
||||
- a motivation for the decomposition
|
||||
|
||||
- black box descriptions of the contained building blocks. For these
|
||||
we offer you alternatives:
|
||||
|
||||
- use *one* table for a short and pragmatic overview of all
|
||||
contained building blocks and their interfaces
|
||||
|
||||
- use a list of black box descriptions of the building blocks
|
||||
according to the black box template (see below). Depending on
|
||||
your choice of tool this list could be sub-chapters (in text
|
||||
files), sub-pages (in a Wiki) or nested elements (in a modeling
|
||||
tool).
|
||||
|
||||
- (optional:) important interfaces, that are not explained in the
|
||||
black box templates of a building block, but are very important for
|
||||
understanding the white box. Since there are so many ways to specify
|
||||
interfaces why do not provide a specific template for them. In the
|
||||
worst case you have to specify and describe syntax, semantics,
|
||||
protocols, error handling, restrictions, versions, qualities,
|
||||
necessary compatibilities and many things more. In the best case you
|
||||
will get away with examples or simple signatures.
|
||||
|
||||
***\<Overview Diagram>***
|
||||
|
||||
Motivation
|
||||
|
||||
: *\<text explanation>*
|
||||
|
||||
Contained Building Blocks
|
||||
|
||||
: *\<Description of contained building block (black boxes)>*
|
||||
|
||||
Important Interfaces
|
||||
|
||||
: *\<Description of important interfaces>*
|
||||
|
||||
Insert your explanations of black boxes from level 1:
|
||||
|
||||
If you use tabular form you will only describe your black boxes with
|
||||
name and responsibility according to the following schema:
|
||||
|
||||
+-----------------------+-----------------------------------------------+
|
||||
| **Name** | **Responsibility** |
|
||||
+=======================+===============================================+
|
||||
| *\<black box 1>* | *\<Text>* |
|
||||
+-----------------------+-----------------------------------------------+
|
||||
| *\<black box 2>* | *\<Text>* |
|
||||
+-----------------------+-----------------------------------------------+
|
||||
|
||||
If you use a list of black box descriptions then you fill in a separate
|
||||
black box template for every important building block . Its headline is
|
||||
the name of the black box.
|
||||
|
||||
### \<Name black box 1> {#__name_black_box_1}
|
||||
|
||||
Here you describe \<black box 1> according the the following black box
|
||||
template:
|
||||
|
||||
- Purpose/Responsibility
|
||||
|
||||
- Interface(s), when they are not extracted as separate paragraphs.
|
||||
This interfaces may include qualities and performance
|
||||
characteristics.
|
||||
|
||||
- (Optional) Quality-/Performance characteristics of the black box,
|
||||
e.g.availability, run time behavior, ....
|
||||
|
||||
- (Optional) directory/file location
|
||||
|
||||
- (Optional) Fulfilled requirements (if you need traceability to
|
||||
requirements).
|
||||
|
||||
- (Optional) Open issues/problems/risks
|
||||
|
||||
*\<Purpose/Responsibility>*
|
||||
|
||||
*\<Interface(s)>*
|
||||
|
||||
*\<(Optional) Quality/Performance Characteristics>*
|
||||
|
||||
*\<(Optional) Directory/File Location>*
|
||||
|
||||
*\<(Optional) Fulfilled Requirements>*
|
||||
|
||||
*\<(optional) Open Issues/Problems/Risks>*
|
||||
|
||||
### \<Name black box 2> {#__name_black_box_2}
|
||||
|
||||
*\<black box template>*
|
||||
|
||||
### \<Name black box n> {#__name_black_box_n}
|
||||
|
||||
*\<black box template>*
|
||||
|
||||
### \<Name interface 1> {#__name_interface_1}
|
||||
|
||||
...
|
||||
|
||||
### \<Name interface m> {#__name_interface_m}
|
||||
|
||||
## Level 2 {#_level_2}
|
||||
|
||||
Here you can specify the inner structure of (some) building blocks from
|
||||
level 1 as white boxes.
|
||||
|
||||
You have to decide which building blocks of your system are important
|
||||
enough to justify such a detailed description. Please prefer relevance
|
||||
over completeness. Specify important, surprising, risky, complex or
|
||||
volatile building blocks. Leave out normal, simple, boring or
|
||||
standardized parts of your system
|
||||
|
||||
### White Box *\<building block 1>* {#_white_box_emphasis_building_block_1_emphasis}
|
||||
|
||||
...describes the internal structure of *building block 1*.
|
||||
|
||||
*\<white box template>*
|
||||
|
||||
### White Box *\<building block 2>* {#_white_box_emphasis_building_block_2_emphasis}
|
||||
|
||||
*\<white box template>*
|
||||
|
||||
...
|
||||
|
||||
### White Box *\<building block m>* {#_white_box_emphasis_building_block_m_emphasis}
|
||||
|
||||
*\<white box template>*
|
||||
|
||||
## Level 3 {#_level_3}
|
||||
|
||||
Here you can specify the inner structure of (some) building blocks from
|
||||
level 2 as white boxes.
|
||||
|
||||
When you need more detailed levels of your architecture please copy this
|
||||
part of arc42 for additional levels.
|
||||
|
||||
### White Box \<\_building block x.1\_\> {#_white_box_building_block_x_1}
|
||||
|
||||
Specifies the internal structure of *building block x.1*.
|
||||
|
||||
*\<white box template>*
|
||||
|
||||
### White Box \<\_building block x.2\_\> {#_white_box_building_block_x_2}
|
||||
|
||||
*\<white box template>*
|
||||
|
||||
### White Box \<\_building block y.1\_\> {#_white_box_building_block_y_1}
|
||||
|
||||
*\<white box template>*
|
||||
|
||||
# Runtime View {#section-runtime-view}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
The runtime view describes concrete behavior and interactions of the
|
||||
system's building blocks in form of scenarios from the following areas:
|
||||
|
||||
- important use cases or features: how do building blocks execute
|
||||
them?
|
||||
|
||||
- interactions at critical external interfaces: how do building blocks
|
||||
cooperate with users and neighboring systems?
|
||||
|
||||
- operation and administration: launch, start-up, stop
|
||||
|
||||
- error and exception scenarios
|
||||
|
||||
Remark: The main criterion for the choice of possible scenarios
|
||||
(sequences, workflows) is their **architectural relevance**. It is
|
||||
**not** important to describe a large number of scenarios. You should
|
||||
rather document a representative selection.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
You should understand how (instances of) building blocks of your system
|
||||
perform their job and communicate at runtime. You will mainly capture
|
||||
scenarios in your documentation to communicate your architecture to
|
||||
stakeholders that are less willing or able to read and understand the
|
||||
static models (building block view, deployment view).
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
There are many notations for describing scenarios, e.g.
|
||||
|
||||
- numbered list of steps (in natural language)
|
||||
|
||||
- activity diagrams or flow charts
|
||||
|
||||
- sequence diagrams
|
||||
|
||||
- BPMN or EPCs (event process chains)
|
||||
|
||||
- state machines
|
||||
|
||||
- ...
|
||||
|
||||
See [Runtime View](https://docs.arc42.org/section-6/) in the arc42
|
||||
documentation.
|
||||
|
||||
## \<Runtime Scenario 1> {#__runtime_scenario_1}
|
||||
|
||||
- *\<insert runtime diagram or textual description of the scenario>*
|
||||
|
||||
- *\<insert description of the notable aspects of the interactions
|
||||
between the building block instances depicted in this diagram.\>*
|
||||
|
||||
## \<Runtime Scenario 2> {#__runtime_scenario_2}
|
||||
|
||||
## ... {#_}
|
||||
|
||||
## \<Runtime Scenario n> {#__runtime_scenario_n}
|
||||
|
||||
# Deployment View {#section-deployment-view}
|
||||
|
||||
::: formalpara-title
|
||||
**Content**
|
||||
:::
|
||||
|
||||
The deployment view describes:
|
||||
|
||||
1. technical infrastructure used to execute your system, with
|
||||
infrastructure elements like geographical locations, environments,
|
||||
computers, processors, channels and net topologies as well as other
|
||||
infrastructure elements and
|
||||
|
||||
2. mapping of (software) building blocks to that infrastructure
|
||||
elements.
|
||||
|
||||
Often systems are executed in different environments, e.g. development
|
||||
environment, test environment, production environment. In such cases you
|
||||
should document all relevant environments.
|
||||
|
||||
Especially document a deployment view if your software is executed as
|
||||
distributed system with more than one computer, processor, server or
|
||||
container or when you design and construct your own hardware processors
|
||||
and chips.
|
||||
|
||||
From a software perspective it is sufficient to capture only those
|
||||
elements of an infrastructure that are needed to show a deployment of
|
||||
your building blocks. Hardware architects can go beyond that and
|
||||
describe an infrastructure to any level of detail they need to capture.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
Software does not run without hardware. This underlying infrastructure
|
||||
can and will influence a system and/or some cross-cutting concepts.
|
||||
Therefore, there is a need to know the infrastructure.
|
||||
|
||||
Maybe a highest level deployment diagram is already contained in section
|
||||
3.2. as technical context with your own infrastructure as ONE black box.
|
||||
In this section one can zoom into this black box using additional
|
||||
deployment diagrams:
|
||||
|
||||
- UML offers deployment diagrams to express that view. Use it,
|
||||
probably with nested diagrams, when your infrastructure is more
|
||||
complex.
|
||||
|
||||
- When your (hardware) stakeholders prefer other kinds of diagrams
|
||||
rather than a deployment diagram, let them use any kind that is able
|
||||
to show nodes and channels of the infrastructure.
|
||||
|
||||
See [Deployment View](https://docs.arc42.org/section-7/) in the arc42
|
||||
documentation.
|
||||
|
||||
## Infrastructure Level 1 {#_infrastructure_level_1}
|
||||
|
||||
Describe (usually in a combination of diagrams, tables, and text):
|
||||
|
||||
- distribution of a system to multiple locations, environments,
|
||||
computers, processors, .., as well as physical connections between
|
||||
them
|
||||
|
||||
- important justifications or motivations for this deployment
|
||||
structure
|
||||
|
||||
- quality and/or performance features of this infrastructure
|
||||
|
||||
- mapping of software artifacts to elements of this infrastructure
|
||||
|
||||
For multiple environments or alternative deployments please copy and
|
||||
adapt this section of arc42 for all relevant environments.
|
||||
|
||||
***\<Overview Diagram>***
|
||||
|
||||
Motivation
|
||||
|
||||
: *\<explanation in text form>*
|
||||
|
||||
Quality and/or Performance Features
|
||||
|
||||
: *\<explanation in text form>*
|
||||
|
||||
Mapping of Building Blocks to Infrastructure
|
||||
|
||||
: *\<description of the mapping>*
|
||||
|
||||
## Infrastructure Level 2 {#_infrastructure_level_2}
|
||||
|
||||
Here you can include the internal structure of (some) infrastructure
|
||||
elements from level 1.
|
||||
|
||||
Please copy the structure from level 1 for each selected element.
|
||||
|
||||
### *\<Infrastructure Element 1>* {#__emphasis_infrastructure_element_1_emphasis}
|
||||
|
||||
*\<diagram + explanation>*
|
||||
|
||||
### *\<Infrastructure Element 2>* {#__emphasis_infrastructure_element_2_emphasis}
|
||||
|
||||
*\<diagram + explanation>*
|
||||
|
||||
...
|
||||
|
||||
### *\<Infrastructure Element n>* {#__emphasis_infrastructure_element_n_emphasis}
|
||||
|
||||
*\<diagram + explanation>*
|
||||
|
||||
# Cross-cutting Concepts {#section-concepts}
|
||||
|
||||
::: formalpara-title
|
||||
**Content**
|
||||
:::
|
||||
|
||||
This section describes overall, principal regulations and solution ideas
|
||||
that are relevant in multiple parts (= cross-cutting) of your system.
|
||||
Such concepts are often related to multiple building blocks. They can
|
||||
include many different topics, such as
|
||||
|
||||
- models, especially domain models
|
||||
|
||||
- architecture or design patterns
|
||||
|
||||
- rules for using specific technology
|
||||
|
||||
- principal, often technical decisions of an overarching (=
|
||||
cross-cutting) nature
|
||||
|
||||
- implementation rules
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
Concepts form the basis for *conceptual integrity* (consistency,
|
||||
homogeneity) of the architecture. Thus, they are an important
|
||||
contribution to achieve inner qualities of your system.
|
||||
|
||||
Some of these concepts cannot be assigned to individual building blocks,
|
||||
e.g. security or safety.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
The form can be varied:
|
||||
|
||||
- concept papers with any kind of structure
|
||||
|
||||
- cross-cutting model excerpts or scenarios using notations of the
|
||||
architecture views
|
||||
|
||||
- sample implementations, especially for technical concepts
|
||||
|
||||
- reference to typical usage of standard frameworks (e.g. using
|
||||
Hibernate for object/relational mapping)
|
||||
|
||||
::: formalpara-title
|
||||
**Structure**
|
||||
:::
|
||||
|
||||
A potential (but not mandatory) structure for this section could be:
|
||||
|
||||
- Domain concepts
|
||||
|
||||
- User Experience concepts (UX)
|
||||
|
||||
- Safety and security concepts
|
||||
|
||||
- Architecture and design patterns
|
||||
|
||||
- \"Under-the-hood\"
|
||||
|
||||
- development concepts
|
||||
|
||||
- operational concepts
|
||||
|
||||
Note: it might be difficult to assign individual concepts to one
|
||||
specific topic on this list.
|
||||
|
||||
|
||||
|
||||
See [Concepts](https://docs.arc42.org/section-8/) in the arc42
|
||||
documentation.
|
||||
|
||||
## *\<Concept 1>* {#__emphasis_concept_1_emphasis}
|
||||
|
||||
*\<explanation>*
|
||||
|
||||
## *\<Concept 2>* {#__emphasis_concept_2_emphasis}
|
||||
|
||||
*\<explanation>*
|
||||
|
||||
...
|
||||
|
||||
## *\<Concept n>* {#__emphasis_concept_n_emphasis}
|
||||
|
||||
*\<explanation>*
|
||||
|
||||
# Architecture Decisions {#section-design-decisions}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
Important, expensive, large scale or risky architecture decisions
|
||||
including rationales. With \"decisions\" we mean selecting one
|
||||
alternative based on given criteria.
|
||||
|
||||
Please use your judgement to decide whether an architectural decision
|
||||
should be documented here in this central section or whether you better
|
||||
document it locally (e.g. within the white box template of one building
|
||||
block).
|
||||
|
||||
Avoid redundancy. Refer to section 4, where you already captured the
|
||||
most important decisions of your architecture.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
Stakeholders of your system should be able to comprehend and retrace
|
||||
your decisions.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
Various options:
|
||||
|
||||
- ADR ([Documenting Architecture
|
||||
Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions))
|
||||
for every important decision
|
||||
|
||||
- List or table, ordered by importance and consequences or:
|
||||
|
||||
- more detailed in form of separate sections per decision
|
||||
|
||||
See [Architecture Decisions](https://docs.arc42.org/section-9/) in the
|
||||
arc42 documentation. There you will find links and examples about ADR.
|
||||
|
||||
# Quality Requirements {#section-quality-scenarios}
|
||||
|
||||
::: formalpara-title
|
||||
**Content**
|
||||
:::
|
||||
|
||||
This section contains all quality requirements as quality tree with
|
||||
scenarios. The most important ones have already been described in
|
||||
section 1.2. (quality goals)
|
||||
|
||||
Here you can also capture quality requirements with lesser priority,
|
||||
which will not create high risks when they are not fully achieved.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
Since quality requirements will have a lot of influence on architectural
|
||||
decisions you should know for every stakeholder what is really important
|
||||
to them, concrete and measurable.
|
||||
|
||||
See [Quality Requirements](https://docs.arc42.org/section-10/) in the
|
||||
arc42 documentation.
|
||||
|
||||
## Quality Tree {#_quality_tree}
|
||||
|
||||
::: formalpara-title
|
||||
**Content**
|
||||
:::
|
||||
|
||||
The quality tree (as defined in ATAM -- Architecture Tradeoff Analysis
|
||||
Method) with quality/evaluation scenarios as leafs.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
The tree structure with priorities provides an overview for a sometimes
|
||||
large number of quality requirements.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
The quality tree is a high-level overview of the quality goals and
|
||||
requirements:
|
||||
|
||||
- tree-like refinement of the term \"quality\". Use \"quality\" or
|
||||
\"usefulness\" as a root
|
||||
|
||||
- a mind map with quality categories as main branches
|
||||
|
||||
In any case the tree should include links to the scenarios of the
|
||||
following section.
|
||||
|
||||
## Quality Scenarios {#_quality_scenarios}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
Concretization of (sometimes vague or implicit) quality requirements
|
||||
using (quality) scenarios.
|
||||
|
||||
These scenarios describe what should happen when a stimulus arrives at
|
||||
the system.
|
||||
|
||||
For architects, two kinds of scenarios are important:
|
||||
|
||||
- Usage scenarios (also called application scenarios or use case
|
||||
scenarios) describe the system's runtime reaction to a certain
|
||||
stimulus. This also includes scenarios that describe the system's
|
||||
efficiency or performance. Example: The system reacts to a user's
|
||||
request within one second.
|
||||
|
||||
- Change scenarios describe a modification of the system or of its
|
||||
immediate environment. Example: Additional functionality is
|
||||
implemented or requirements for a quality attribute change.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
Scenarios make quality requirements concrete and allow to more easily
|
||||
measure or decide whether they are fulfilled.
|
||||
|
||||
Especially when you want to assess your architecture using methods like
|
||||
ATAM you need to describe your quality goals (from section 1.2) more
|
||||
precisely down to a level of scenarios that can be discussed and
|
||||
evaluated.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
Tabular or free form text.
|
||||
|
||||
# Risks and Technical Debts {#section-technical-risks}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
A list of identified technical risks or technical debts, ordered by
|
||||
priority
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
"Risk management is project management for grown-ups" (Tim Lister,
|
||||
Atlantic Systems Guild.)
|
||||
|
||||
This should be your motto for systematic detection and evaluation of
|
||||
risks and technical debts in the architecture, which will be needed by
|
||||
management stakeholders (e.g. project managers, product owners) as part
|
||||
of the overall risk analysis and measurement planning.
|
||||
|
||||
::: formalpara-title
|
||||
**Form**
|
||||
:::
|
||||
|
||||
List of risks and/or technical debts, probably including suggested
|
||||
measures to minimize, mitigate or avoid risks or reduce technical debts.
|
||||
|
||||
See [Risks and Technical Debt](https://docs.arc42.org/section-11/) in
|
||||
the arc42 documentation.
|
||||
|
||||
# Glossary {#section-glossary}
|
||||
|
||||
::: formalpara-title
|
||||
**Contents**
|
||||
:::
|
||||
|
||||
The most important domain and technical terms that your stakeholders use
|
||||
when discussing the system.
|
||||
|
||||
You can also see the glossary as source for translations if you work in
|
||||
multi-language teams.
|
||||
|
||||
::: formalpara-title
|
||||
**Motivation**
|
||||
:::
|
||||
|
||||
You should clearly define your terms, so that all stakeholders
|
||||
|
||||
- have an identical understanding of these terms
|
||||
|
||||
- do not use synonyms and homonyms
|
||||
|
||||
A table with columns \<Term> and \<Definition>.
|
||||
|
||||
Potentially more columns in case you need translations.
|
||||
|
||||
See [Glossary](https://docs.arc42.org/section-12/) in the arc42
|
||||
documentation.
|
||||
|
||||
+-----------------------+-----------------------------------------------+
|
||||
| Term | Definition |
|
||||
+=======================+===============================================+
|
||||
| *\<Term-1>* | *\<definition-1>* |
|
||||
+-----------------------+-----------------------------------------------+
|
||||
| *\<Term-2>* | *\<definition-2>* |
|
||||
+-----------------------+-----------------------------------------------+
|
||||
BIN
Binary file not shown.
|
After Width: | Height: | Size: 81 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 275 KiB |
BIN
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.0 KiB |
Reference in New Issue
Block a user