Skip to content

A local-first personal finance app

basics of text style guide for consistent tone when writing. (#398)

wdpkf13cc304ed82
diff --git a/.github/actions/spelling/allow/keywords.txt b/.github/actions/spelling/allow/keywords.txt
index c9ec56aeaa..68b9af36c1 100644
--- a/.github/actions/spelling/allow/keywords.txt
+++ b/.github/actions/spelling/allow/keywords.txt
@@ -42,6 +42,7 @@ Formik
Fortuneo
gebabebb
GEBABEBB
+Greenshot
HSA
htpasswd
IBANs
@@ -63,6 +64,7 @@ ldaplogin
letsencrypt
libofx
linting
+Linuxes
linuxsvg
lleskassen
lte
diff --git a/.gitignore b/.gitignore
index 3831b64000..98d8681d43 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,9 @@
.DS_Store
+.idea
+*.iml
+
npm-debug.log*
yarn-debug.log*
yarn-error.log*
diff --git a/README.md b/README.md
index 447e0ab170..45b2514989 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,9 @@ This repo is the Actual Budget community documentation website, built using [Doc
## Welcome
-Firstly, thank you for stopping by and giving up some of your time to either check out the documentation we have already produced or pick off some of the [issues](https://github.com/actualbudget/docs/issues) and help create some new documentation for our future users.
+Firstly, thank you for stopping by and giving up some of your time to either check out the documentation we have already produced or pick off
+some of the [issues](https://github.com/actualbudget/docs/issues) and help create some new documentation for our future users. Check out the
+[guidelines](https://actualbudget.org/docs/contributing/writing-docs) for more information on how the documentation is structured and tips for consistent formatting.
### Installation Methods
@@ -23,150 +25,6 @@ If you would like to write documentation for another installation variant, pleas
However, in doing so, you would become responsible for these instructions. If they become out of date or people want in-depth help with them, we will point them to you for assistance if the community is unable to help. If lots of people report issues with them, we may have to remove the link altogether.
-## Document Standards
-
-Below are some basic standards on how the documentation should be formatted. Everyone has their own writing style, but the layout of the documents should be the same across all documents.
-
-### Language
-
-When writing your documentation, please use the English language. At this time, the documentation team doesn't have any translators available to translate documents into other languages, but this is something we would like to do in the future.
-
-Docusaurus 2 provides translation using [i18n](https://docusaurus.io/docs/i18n/introduction). If this is something you would like to pursue, please feel free to open a PR.
-
-### Documentation Structure
-
-Below is the documentation structure for the Actual Community Docs.
-
-```
-website # the root directory of the documentation site
-├── docs
-│ └── index.md # the introduction file
-│ └── faq.md
-│ └── releases.md # release notes
- └── accounts # Anything relating to accounts, account management or transactions
- ...
- └── advanced # Some more advanced guides for Actual
- └── scripts
- ...
- └── backup-restore
- ...
- └── budgeting # Budget specific, including rules, schedules etc.
- └── rules
- ...
- └── contributing # How to contribute, project structures etc.
- ...
- └── experimental # Documentation for experimental features
- ...
- └── getting-started # Getting started with Actual
- ...
- └── install # Documentation around installing actual
- ...
- └── migration # Migrating into Actual and using the tools available.
- ...
- └── reports
- ...
- └── tour
- ...
- └── transactions
- ...
- └── troubleshooting
- ...
-│
-└── static
- └── img
-```
-
-### Document Frontmatter
-
-Front matter is used to add metadata to your documentation file. The front matter is used to enrich the default metadata inferred from the content or other configuration.
-
-```markdown
----
-title: My Doc Title
-more_data:
- - Can be provided
- - as: objects
- or: arrays
----
-```
-
-### Document Headings
-
-The below shows how a document should be laid out.
-
-`# A single heading`
-
-Each document should only have one single heading. When a title is not provided in the front matter of the document, the heading provided is used instead and displayed in the documentation tree.
-
-`## Sub Headings to split out sections of your document`
-
-Subheadings are used to split the document into meaningful "chapters." These are then used in the right sidebar when viewing a document to allow the reader to easily navigate the document content.
-
-`### Section subheadings.`
-
-Each "chapter" can then be split into subsections using three-gate headings.
-
-### When Using Images
-
-> Screenshots taken on a retina screen should be titled as such: [email protected]
-> This allows Docusaurus to rescale the images where appropriate.
-
-When using images, ensure that the image is large and clear. If the image contains multiple items and buttons, highlight the area you are talking about (as shown below) or create arrows on the image to point to the part you are discussing. Where possible, images should be saved as `PNG` format. Screenshots should be taken using 'light' mode color theme.
-
-The clearest way to highlight areas on a screenshot is the 'transparency' box.
-
-![](./static/img/repo/highlighting.png)
-
-If a transparency box isn't available in your image editor, use an arrow or a colored box with hex: `#d5805a` / rgb: `213, 128, 90` (an analogous shade of orange to Actual's purple). If it's not practical to be that precise, just pick one as close as you can.
-
-#### Generic Images and Directory Structures
-
-In order to minimize the workload for adding images and make updating images easier, there's a directory containing regularly used images.
-
-For example, many feature instructions may first require the user to navigate to a standard menu, e.g.,
-
-> "Click on 'Settings' in the sidebar"
-> [inserted image of the settings button in the sidebar]
-
-In this case, the relevant screenshot is found at `/static/img/elements/sidebar/[email protected]`, along with all other possible menu selections in the sidebar.
-
-If there's an image missing from any of the respective folders in `elements/`, feel free to add one yourself following the same naming scheme.
-
-All other screenshots for the page you are working on should be placed in the respective folder in the `img/` directory. e.g., when working on a page titled 'cool-feature', images should be placed in the `static/img/cool-feature/` folder.
-
-### Call Outs
-
-If you would like to highlight a section of your document with a note, you can use the following:
-
-```markdown
-:::notes
-Your note content
-:::
-```
-
-If you want to make a reader aware of a cautionary item in your documentation, you can use this:
-
-```markdown
-:::caution
-Your cautionary item
-:::
-```
-
-### Quotes & Code Blocks
-
-Using quotes within your documentation is easy to do using:
-
-```markdown
-> Your quote goes here
-> another line of your quote
-> and another
-```
-
-If you want to use code in your documentation, that is easy too.
-
-```js
-console.log('Every repo must come with a mascot.');
-```
## Contributing 
@@ -224,4 +82,5 @@ If you are using GitHub pages for hosting, this command is a convenient way to b
### Writing Good Release Notes
-For general guidelines, see [contributing](https://actualbudget.org/docs/contributing/#writing-good-release-notes) section of the documentation. The Documentation site is not versioned in the same manner as the rest of the project. The Documentation website is more of a living document. Merges into `master` will have the title and PR# as commit message, with the PR description as extended git commit description.
+For general guidelines, see [Contributing](https://actualbudget.org/docs/contributing/#writing-good-release-notes) section of the documentation. The Documentation site is not versioned in the same manner as the rest of the project. The Documentation website is more of a living document. Merges into `master` will have the title and PR# as commit message, with the PR description as extended git commit description.
+
diff --git a/docs-sidebar.js b/docs-sidebar.js
index ed7cda8dd2..4f6d7707a7 100644
--- a/docs-sidebar.js
+++ b/docs-sidebar.js
@@ -307,6 +307,14 @@ const sidebars = {
'contributing/releasing',
'contributing/windows',
{
+ type: 'category',
+ label: 'Documentation',
+ collapsible: false,
+ items: [
+ 'contributing/writing-docs',
+ ],
+ },
+ {
type: 'category',
label: 'Project Leadership',
collapsible: false,
diff --git a/docs/contributing/writing-docs.md b/docs/contributing/writing-docs.md
new file mode 100644
index 0000000000..3eacc7ecbb
--- /dev/null
+++ b/docs/contributing/writing-docs.md
@@ -0,0 +1,384 @@
+# Writing Documentation
+
+Except for a few sections, most of the documentation is aimed at end users. It is important to keep this in mind when writing documentation. In practice, this means that it is better to be a bit verbose and write out every step in a process than assume that the reader is on the writer's technical level.
+
+<details><summary>Read example</summary>
+
+For those with experience, the process is straightforward and familiar: _To update with our latest releases, simply use the `git pull` command from the `master` branch of your local directory of Actual. Once the changes are updated, execute the `yarn install` to download the latest updates from the releases._
+
+A better approach for inexperienced people, as it explains what each step is doing and the expected outcome.:
+
+1. Stop the server if it's running. You can use the keyboard shortcut <Key mod= "ctrl" k= "c"/> (even on macOS) to stop the server or close the terminal window it's running from.
+2. Run `git pull` from the directory you cloned the project into. This will download the latest server code.
+3. Run `yarn install` from that same directory. This will download the latest web client code and any updated dependencies for the server.
+4. Restart the server by running `yarn start`.
+
+</details>
+
+We generate our website using the [Docusaurus](https://docusaurus.io/) system, and our documentation is written in Markdown (+ some Docusaurus specifics).
+
+
+If you're interested in contributing, you'll need to know about the following two resources:
+
+* [Actual documentation repository on GitHub](https://github.com/actualbudget/docs)
+* [Actual Budget #documentation channel on Discord](https://discord.com/channels/937901803608096828/1027831463103696928)
+
+
+
+## Documentation Structure
+
+
+### Document Front Matter
+
+Front matter is used to add metadata to the documentation file. The front matter enriches the default metadata inferred from the content or other configuration.
+
+Using front matter is not mandatory.
+
+```markdown
+---
+title: My Doc Title
+more_data:
+ - Can be provided
+ - as: objects
+ or: arrays
+---
+```
+
+
+### Document Headings and Subheadings
+
+We follow a strict, mandatory, structure in our documents by using Markdown headings.
+
+If the title tag is not provided in the front matter, you must start the document with a level 1 heading.
+If the title tag is provided, you must omit this level 1 heading.
+Each document should have only one level 1 heading.
+
+`# Level 1 Markdown Heading is used instead as The Document Title if Front Matter title tag is not used`
+
+Many documents are divided into multiple main sections for improved readability and organization, with level 2 headings serving as the method for structuring the content.
+
+Use level 3 headings when a main section becomes complex and requires further breakdown.
+
+Additionally, if necessary, a fourth level of headings is available to provide even more detailed categorization.
+
+It is important to note that both level 1 and level 2 headings are prominently displayed in the right sidebar, making it easier for readers to navigate the document and locate specific sections efficiently.
+
+```markdown
+## Level 2 Markdown Heading: Main Section Headings are used to split the document into main sections
+### Level 3 Markdown Heading: Subsections Headings are used to split each section
+#### Level 4 Markdown Heading: Use this if you need to split the Subsection further
+```
+
+
+
+
+### Documentation folder structure
+
+The documentation folder structure should follow the structure in the left of the screen.
+This means sections with more than one page have their own directories.
+
+
+<details><summary>Click here to get an overview of the folder structure</summary>
+
+```
+website # the root directory of the documentation site
+├── docs
+│ └── index.md # the introduction file
+│ └── faq.md
+│ └── releases.md # release notes
+ └── accounts # Anything relating to accounts, account management or transactions
+ ...
+ └── advanced # Some more advanced guides for Actual
+ └── scripts
+ ...
+ └── backup-restore
+ ...
+ └── budgeting # Budget specific, including rules, schedules etc.
+ └── rules
+ ...
+ └── contributing # How to contribute, project structures etc.
+ ...
+ └── experimental # Documentation for experimental features.
+ ...
+ └── getting-started # Getting started with Actual.
+ ....
+ └── install # Documentation around installing actual.
+ ...
+ └── migration # Migrating into Actual and using the tools available.
+ ...
+ └── reports # Everything reporting.
+ ...
+ └── tour # The Actual Tour.
+ ...
+ └── transactions # Handling transactions.
+ ...
+ └── troubleshooting # Hints and tips regarding troubles.
+ ...
+│
+└── static
+ └── img
+```
+
+</details>
+
+## Document Guidelines
+
+Below are some basic guidelines on how the documentation should be formatted. Everyone has their own writing style, but we aim to keep the style of the documentation the same across the site.
+
+### Language
+
+When writing documentation, please use the English language. At this time, the documentation team doesn't have any translators available to translate documents into other languages, but this is something we would like to do in the future.
+
+Docusaurus 2 provides translation using [i18n](https://docusaurus.io/docs/i18n/introduction). If this is something you would like to pursue, please feel free to open a PR.
+
+### Tone and Voice
+
+* **Friendly and Approachable**: Write in a conversational and welcoming tone. The goal is to make users feel comfortable and supported.
+
+* **Active Voice**: Use active voice to make sentences more direct and engaging. Example: _Install Actual Budget on your computer_ instead of _Actual Budget should be installed on your computer_.
+
+* **Time Neutral**: Use present voice, unless documentation is for experimental or unreleased features. Where time references are made, remove them upon release or removal of the feature. Example: _Filters can be used..._ instead of _As of June 2022 update, you can..._.
+
+### Format
+
+* **Keep paragraphs short and focused**. Each paragraph should convey a single idea or concept.
+
+* **Use bullet points** or numbered lists to break down information into digestible chunks.
+
+* **Consistent Terminology**: Use consistent terminology throughout the documentation. Refer to the product as "Actual Budget" or "Actual."
+
+
+## Formatting text
+
+All documentation is written in Markdown, with certain additional Markdown syntax provided by Docusaurus.
+
+If you have never used Markdown, please consult [CommonMark](https://commonmark.org/) and the
+[Docusaurus Markdown Features](https://docusaurus.io/docs/markdown-features) guide. You can learn more about Markdown in
+[The Markdown Guide](https://www.markdownguide.org/).
+
+### Keyboard shortcuts
+
+
+```markdown
+<Key k="f" /> shows the f-key.
+<Key k="enter" /> shows the Enter-key.
+<Key mod="shift" k="enter" /> shows the Shift-Enter key combination.
+<Key mod="cmd" k="enter" /> shows the Command-Enter key combination.
+```
+
+#### The above will be rendered as follows
+
+* <Key k="f" /> shows the f-key.
+* <Key k="enter" /> shows the Enter-key.
+* <Key mod="shift" k="enter" /> shows the Shift-Enter key combination.
+* <Key mod="cmd" k="enter" /> shows the Command-Enter key combination.
+
+
+### Highlights
+
+If you would like to highlight a section of the document you can use the following:
+
+```markdown
+:::tip
+Your tip content
+:::
+```
+
+
+```markdown
+:::note
+Your note content
+:::
+```
+
+If you want to make a reader aware of a cautionary item in the documentation, you can use this:
+
+```markdown
+:::caution
+Your cautionary item
+:::
+```
+
+#### The above highlights will be rendered as follows
+:::tip
+Your tip content
+:::
+
+:::note
+Your note content
+:::
+
+:::caution
+Your cautionary item
+:::
+
+
+### Hiding and showing information
+
+
+<details><summary>This is a summary box, click here to see how it's made</summary>
+
+`<details><summary>The title of the summary</summary>`
+
+Place the content inside the details-tags.
+
+`</details>`
+
+
+</details>
+
+
+## Naming Standards
+
+### For documents
+
+* Filenames should be self-explanatory and reflect the title of the file.
+* A longer, more descriptive, filename is preferred over a shorter, less descriptive, one.
+* Folder names must reflect the naming in the sidebar.
+
+### For images
+
+* Images must be placed in the `/static/img/` folder.
+* Except for logos and such, all images related to the documentation must be placed in a folder corresponding to the location of the document in which it is used. Let's say you want to add an image to a document in the `/docs/budgeting/` folder - the corresponding images must be stored in the `/static/img/budgeting/` folder.
+* Image names must be prefixed to correspond with the document they primarily belong to. Let's say you are adding an image to the `/docs/budgeting/categories.md` file, then all image names need to be prefixed with `categories-`.
+* For regularly used images, these can be put into `/static/img/elements/`, inside it's own folders. Let's say you want to store images related to the sidebar; then all _sidebar_ images need to be placed in `/static/images/elements/sidebar/`. We have decided to do it this way to minimize the workload when adding and updating images.
+
+
+## Using Images
+
+Using images to accompany the description makes the documentation more accessible, thus improving its readability.
+
+The way to do this is to take good screenshots. When taking screenshots, there are a few things to keep in mind:
+
+* It is crucial to ensure that the image is crystal clear and directly relevant.
+ Blurry or muddled images can detract from the user's understanding and confidence in the documentation.
+* Striking the right balance on how much a screenshot should include is vital. Too much information can overwhelm the reader,
+ while too little can leave them without the necessary context. Your judgment in
+ this matter is crucial to the effectiveness of the documentation.
+* Avoid taking screenshots on a big screen when the browser is in full-screen mode.
+ Try to take screenshots at most 1100 pixels wide and 700 pixels long. By this, we do not mean the size of the
+ finished images but how much of the screen you are taking a picture of.
+* Images must always be saved in the PNG format.
+* Take images using only the _light_ mode, not _dark_.
+* If you need to address more than one part of the screenshot, annotate the image. See below for more details.
+ * We strongly encourage you to always add _alt text_ to the images, as not all image names are self-explanatory.
+
+:::info
+Screenshots taken on a retina screen should be titled as such: [email protected]. This allows Docusaurus
+to rescale the images where appropriate.
+:::
+
+
+
+
+### Annotating Images
+
+
+There are several reasons why you need to annotate screenshots.
+One reason is that you need want readers to pay attention to some aspects of the GUI. This is true if you have a screenshot of an area (for context) and you need to highlight one part of that area. Another reason is that you must address more than one element in the GUI, but presenting several variants of the same screenshot is unfavourable.
+We have a few suggestions when annotating screenshots:
+
+
+#### Do use boxes over arrows
+Arrows can inadvertently be misunderstood as pointing _from_ something rather than _to_. As we see in the example below, the reader can not be sure if the arrow means the column, the column header or if _To Budget_ is involved.
+
+![Image of the budget view annotated by a box and an arrow](/static/img/repo/annotation-boxes-over-arrows.png)
+
+
+Use "steps" when referring to several elements
+
+Use running numbers or letters inside circles, also known as "steps", when addressing more than one element in the screenshot. If there is a sequence to what a user is going to click on, use step numbers; if you want to address various elements, letters are preferred.
+
+![Image with 3 annotation steps](/static/img/repo/annotation-steps.png)
+
+If the annotation tool doesn't support 'steps ', use boxes in different colors and incorporate these colors into the explanation. This will help guide the reader's attention effectively.
+
+![Image with 3 different colored boxes](/static/img/repo/annotation-colour-boxes.png)
+
+
+<details><summary>Read example description of this way of annotating</summary>
+
+
+**Using _steps_**
+
+a. Formatting numbers. We support most commonly used formats.
+
+b. Choose the date format that you are most comfortable with.
+
+c. The first day of the week controls grouping on reports.
+
+----
+
+
+**Using colored boxes**:
+
+* Formatting numbers (indicated by the red box). We support most formats that are commonly used.
+* If you want to change the date format you are most comfortable with, you can use the dropdown in the green box.
+* The first day of the week controls grouping on reports. You will find this control indicated in the yellow box.
+
+</details>
+
+
+#### Do not draw annotations using "free hand"
+
+Do not use free hand "marker pens", boxes or arrows, as these kind of annotations just look sloppy. Ask for help on the
+[Actual Budget #documentation Discord channel](https://discord.com/channels/937901803608096828/1027831463103696928)
+if you need to annotate images but are not able to do it yourself.
+
+![Image with ugly free-hand annotations](/static/img/repo/annotation-free-hand.png)
+
+
+#### Annotation Colours
+
+Use strong, clear, and crisp colors to create good contrasts. Do not use pure white or pure black. Even if we want
+all screenshots taken using the light theme, there are dark elements like the sidebar and particular dropdowns in the
+GUI. Avoid annotating these elements using dark colors.
+
+Remember that colors are tricky for color blind people.
+
+We suggest using the following colors (RGB values):
+
+| Colour name | Decimal | Hex |
+|------------|---------------|----------|
+| Red | 255, 89, 75 | FF 59 4B |
+| Yellow | 251, 186, 0 | FB BA 00 |
+| Purple | 119, 64, 154 | 77 40 9A |
+| Blue | 112, 175, 253 | 70 AF FD |
+| Green | 0, 187, 161 | 00 BB A1 |
+
+![Annotation colors as seen in the table](/static/img/repo/annotation-colours.png)
+
+For accessibility reasons (color blindness), avoid using red and green annotation colors on the same image.
+
+#### Avoid using _transparency_ or _spotlight_ annotations
+
+Different annotation tools handle this in various ways, which means we will get inconsistent screenshots. Secondly, unless you can control the opacity and color of the highlight, using highlighting could easily confuse more than enlighten the reader. Can you quickly find the highlighted number in the screenshot below?
+
+
+![Image of the budget view using the dark theme showing how highlights or spotlight annotations make the image hard to read](/static/img/repo/annotation-highlights-are-bad.png)
+
+<details><summary>It might work when using the light theme</summary>
+
+However, because we dim down the rest of the image, this breaks over the notion that images should be clear and crisp.
+
+![Image of the budget view using the light theme showing that highlights may work](/static/img/repo/annotation-highlights-ligth-theme.png)
+
+</details>
+
+
+
+### Software For Taking and Annotating Screenshots
+
+There are many software packages available to help you take screenshots. Both Windows and Mac systems come with some rudimentary tools for this (like [Windows Snipping Tool](https://support.microsoft.com/en-us/windows/use-snipping-tool-to-capture-screenshots-00246869-1843-655f-f220-97299b865f6b) or in [MacOS](https://support.apple.com/en-us/102646)). For various Linuxes, [this Fosspost.com article](https://fosspost.org/take-screenshot-linux) can be consulted.
+
+Some of the mentioned tools will let you annotate screenshots, others will not.
+
+If you are serious about your screenshots (and also outside helping out with the Actual documentation), you might want to consider tools created explicitly for taking screenshots and having good annotation support. This list is not an endorsement from the Actual Budget project team but is meant as a starting point for such tools.
+
+**For Windows and Mac**:
+
+* [Greenshot](https://getgreenshot.org/) is a simple and effective open-source solution.
+* [Flameshot](https://flameshot.org/) is a complete open-source package for taking and annotating screenshots. This program is more complex than Greenshot.
+* Many consider [SnagIt](https://www.techsmith.com/screen-capture.html) the best tool in this category, but it comes at a cost.
+
+**For Linux**, please see this [Fosspost.com article](https://fosspost.org/take-screenshot-linux).
diff --git a/static/img/repo/annotation-boxes-over-arrows.png b/static/img/repo/annotation-boxes-over-arrows.png
new file mode 100644
index 0000000000..a2b958aaa0
Binary files /dev/null and b/static/img/repo/annotation-boxes-over-arrows.png differ
diff --git a/static/img/repo/annotation-colour-boxes.png b/static/img/repo/annotation-colour-boxes.png
new file mode 100644
index 0000000000..f2dee4ff40
Binary files /dev/null and b/static/img/repo/annotation-colour-boxes.png differ
diff --git a/static/img/repo/annotation-colours.png b/static/img/repo/annotation-colours.png
new file mode 100644
index 0000000000..0cd6df7949
Binary files /dev/null and b/static/img/repo/annotation-colours.png differ
diff --git a/static/img/repo/annotation-free-hand.png b/static/img/repo/annotation-free-hand.png
new file mode 100644
index 0000000000..21cc0fc8d1
Binary files /dev/null and b/static/img/repo/annotation-free-hand.png differ
diff --git a/static/img/repo/annotation-highlights-are-bad.png b/static/img/repo/annotation-highlights-are-bad.png
new file mode 100644
index 0000000000..fbbff48f7f
Binary files /dev/null and b/static/img/repo/annotation-highlights-are-bad.png differ
diff --git a/static/img/repo/annotation-highlights-ligth-theme.png b/static/img/repo/annotation-highlights-ligth-theme.png
new file mode 100644
index 0000000000..ec8ed0abf4
Binary files /dev/null and b/static/img/repo/annotation-highlights-ligth-theme.png differ
diff --git a/static/img/repo/annotation-steps.png b/static/img/repo/annotation-steps.png
new file mode 100644
index 0000000000..b8654a6d75
Binary files /dev/null and b/static/img/repo/annotation-steps.png differ
diff --git a/static/img/repo/highlighting.png b/static/img/repo/highlighting.png
deleted file mode 100644
index 683f9ddaf4..0000000000
Binary files a/static/img/repo/highlighting.png and /dev/null differ