From 8ec170d063cff4ba079f6bf84d83e02a1bc69966 Mon Sep 17 00:00:00 2001
From: mjh316 <61671361+mjh316@users.noreply.github.com>
Date: Thu, 30 Dec 2021 20:12:21 -0800
Subject: [PATCH 1/8] footer keeps track of main contributor

---
 source/_ext/gitstamp.py               | 51 ++++++++++++++++++++-------
 source/_templates/include/footer.html | 28 +++++++++++----
 2 files changed, 60 insertions(+), 19 deletions(-)

diff --git a/source/_ext/gitstamp.py b/source/_ext/gitstamp.py
index ea13f6b65..b7fb75512 100644
--- a/source/_ext/gitstamp.py
+++ b/source/_ext/gitstamp.py
@@ -28,6 +28,7 @@ class GHCachedUser:
     def __init__(self, name):
         self.name = name
         self.login = None
+        self.commits = None
         self.avatar_url = "/_static/images/user-placeholder.png"
 
 def page_context_handler(app, pagename, templatename, context, doctree):
@@ -44,6 +45,11 @@ def page_context_handler(app, pagename, templatename, context, doctree):
 
     try:
         commits = g.iter_commits('--all', max_count=1, paths="%s.rst" % fullpagename)
+        # Splits on newline to get the first (highest commits) contributor, then handles whitespace, then gets info
+        most_commits, _most_user = g.git.shortlog('-sne', '--', ("%s.rst" % fullpagename)).split('\n')[0].strip().split('\t')
+        # Parses all of 'first_name last_name <email>', 'first_name middle_name last_name <email>', and 'name <email>' correctly
+        most_user_name, most_user_email = ' '.join(_most_user.split(' ')[:-1]), _most_user.split(' ')[-1][1:-1]
+        
         if not commits:
             # Don't datestamp generated rst's (e.g. imapd.conf.rst)
             # Ideally want to check their source - lib/imapoptions, etc, but
@@ -52,32 +58,51 @@ def page_context_handler(app, pagename, templatename, context, doctree):
 
         commit = next(iter(commits))
         context['gitstamp'] = datetime.datetime.fromtimestamp(commit.authored_date).strftime("%Y&#8209;%m&#8209;%d")
+        #raise Exception(f'{commit.author.email} \n {most_user_name, most_user_email}')
 
-        user = GHCachedUser(commit.author.name)
+        last_user = GHCachedUser(commit.author.name)
+        main_user = GHCachedUser(most_user_name)
+        main_user.commits = most_commits
         if 'gh' in globals():
             # Look in cache first to avoid spamming GitHub
             if commit.author.email in gh_user_cache:
-                user = gh_user_cache[commit.author.email]
+                last_user = gh_user_cache[commit.author.email]
             else:
                 # Search GitHub and retrieve first user with matching email (if any)
                 gh_users = gh.search_users(commit.author.email)
                 if gh_users.totalCount:
                     gh_user = next(iter(gh_users))
-                    user.name = gh_user.name
-                    user.login = gh_user.login
-                    user.avatar_url = gh_user.avatar_url
+                    last_user.name = gh_user.name
+                    last_user.login = gh_user.login
+                    last_user.avatar_url = gh_user.avatar_url
                 else:
                     # Try searching the commit hash instead
                     gh_commit = gh_repo.get_commit(commit.hexsha)
                     if gh_commit:
-                        user.name = gh_commit.author.name
-                        user.login = gh_commit.author.login
-                        user.avatar_url = gh_commit.author.avatar_url
-
-                gh_user_cache[commit.author.email] = user
-        context['gitauthor'] = user.name
-        context['gitlogin'] = user.login
-        context['gitavatar'] = user.avatar_url
+                        last_user.name = gh_commit.author.name
+                        last_user.login = gh_commit.author.login
+                        last_user.avatar_url = gh_commit.author.avatar_url
+
+                gh_user_cache[commit.author.email] = last_user
+            # Repeat above for most user
+            if most_user_email in gh_user_cache:
+                main_user = gh_user_cache[most_user_email]
+            else:
+                gh_users = gh.search_users(most_user_email)
+                if gh_users.totalCount:
+                    gh_user = next(iter(gh_users))
+                    main_user.name = gh_user.name
+                    main_user.login = gh_user.login
+                    main_user.avatar_url = gh_user.avatar_url
+
+        context['gitLastAuthor'] = last_user.name
+        context['gitLastLogin'] = last_user.login
+        context['gitLastAvatar'] = last_user.avatar_url
+        context['gitMainAuthor'] = main_user.name
+        context['gitMainLogin'] = main_user.login
+        context['gitMainAvatar'] = main_user.avatar_url
+        context['gitMainCommits'] = main_user.commits
+
 
     except git.exc.GitCommandError:
         # File doesn't exist or something else went wrong.
diff --git a/source/_templates/include/footer.html b/source/_templates/include/footer.html
index ae9db03d4..aa37365ba 100644
--- a/source/_templates/include/footer.html
+++ b/source/_templates/include/footer.html
@@ -1,14 +1,24 @@
 <div class="feedback-footer row hidden-sm hidden-xs">
     <div class="col-xs-4">
     {% if edit_on_github_url %}
-        {%- if gitauthor -%}<p class="git-info" style="text-align: right;">
-            {%- if gitavatar -%}<img src="{{ gitavatar }}" class="git-info-image">{%- endif -%}
+        {%- if gitLastAuthor -%}<p class="git-info" style="text-align: right;">
+            {%- if gitLastAvatar -%}<img src="{{ gitLastAvatar }}" class="git-info-image">{%- endif -%}
             Last updated by
-            {%- if gitlogin %} <a href="https://github.com/{{ gitlogin }}" target="_blank" rel="noopener noreferrer">{{ gitauthor }}</a>{% else %} {{ gitauthor }}{%- endif %}
+            {%- if gitLastLogin %} <a href="https://github.com/{{ gitLastLogin }}" target="_blank" rel="noopener noreferrer">{{ gitLastAuthor }}</a>{% else %} {{ gitLastAuthor }}{%- endif %}
             on {{ gitstamp }}.</p>
         {%- endif %}
     {% endif %}
     </div>
+    <div class="col-xs-4">
+        {% if edit_on_github_url %}
+            {%- if gitMainAuthor -%}<p class="git-info" style="text-align: right;">
+                {%- if gitMainAvatar -%}<img src="{{ gitMainAvatar }}" class="git-info-image">{%- endif -%}
+                Main contributor
+                {%- if gitMainLogin %} <a href="https://github.com/{{ gitMainLogin }}" target="_blank" rel="noopener noreferrer">{{ gitMainAuthor }}</a>{% else %} {{ gitMainAuthor }}{%- endif %}
+                with {{ gitMainCommits }} commit(s).</p>
+            {%- endif %}
+        {% endif %}
+    </div>
     <div class="col-xs-5 feedback-center">
         <p>
             {% trans %}Did you find what you were looking for?{% endtrans %}
@@ -22,12 +32,18 @@
 </div>
 <div class="feedback-footer hidden-lg hidden-md feedback-center">
     {% if edit_on_github_url %}
-        {%- if gitauthor -%}<p class="git-info">
-            {%- if gitavatar -%}<img src="{{ gitavatar }}" class="git-info-image" width="32" height="32">{%- endif -%}
+        {%- if gitLastAuthor -%}<p class="git-info">
+            {%- if gitLastAvatar -%}<img src="{{ gitLastAvatar }}" class="git-info-image" width="32" height="32">{%- endif -%}
             Last updated by
-            {%- if gitlogin %} <a href="https://github.com/{{ gitlogin }}" target="_blank" rel="noopener noreferrer">{{ gitauthor }}</a>{% else %} {{ gitauthor }}{%- endif %}
+            {%- if gitLastLogin %} <a href="https://github.com/{{ gitLastLogin }}" target="_blank" rel="noopener noreferrer">{{ gitLastAuthor }}</a>{% else %} {{ gitLastAuthor }}{%- endif %}
             on {{ gitstamp }}.</p>
         {%- endif %}
+        {%- if gitMainAuthor -%}<p class="git-info">
+            {%- if gitMainAvatar -%}<img src="{{ gitMainAvatar }}" class="git-info-image" width="32" height="32">{%- endif -%}
+            Main contributor
+            {%- if gitMainLogin %} <a href="https://github.com/{{ gitMainLogin }}" target="_blank" rel="noopener noreferrer">{{ gitMainAuthor }}</a>{% else %} {{ gitMainAuthor }}{%- endif %}
+            with {{ gitMainCommits }} commit(s).</p>
+        {%- endif %} 
     {% endif %}
     <p>
         {% trans %}Did you find what you were looking for?{% endtrans %}

From ce3ea34b7613681f2c599462c4e6c2723d9568d1 Mon Sep 17 00:00:00 2001
From: mjh316 <61671361+mjh316@users.noreply.github.com>
Date: Thu, 30 Dec 2021 20:14:06 -0800
Subject: [PATCH 2/8] footer displays main contributor

---
 source/_ext/gitstamp.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/_ext/gitstamp.py b/source/_ext/gitstamp.py
index b7fb75512..ce64c1977 100644
--- a/source/_ext/gitstamp.py
+++ b/source/_ext/gitstamp.py
@@ -58,7 +58,6 @@ def page_context_handler(app, pagename, templatename, context, doctree):
 
         commit = next(iter(commits))
         context['gitstamp'] = datetime.datetime.fromtimestamp(commit.authored_date).strftime("%Y&#8209;%m&#8209;%d")
-        #raise Exception(f'{commit.author.email} \n {most_user_name, most_user_email}')
 
         last_user = GHCachedUser(commit.author.name)
         main_user = GHCachedUser(most_user_name)
@@ -84,7 +83,7 @@ def page_context_handler(app, pagename, templatename, context, doctree):
                         last_user.avatar_url = gh_commit.author.avatar_url
 
                 gh_user_cache[commit.author.email] = last_user
-            # Repeat above for most user
+            # Repeat above for main_user
             if most_user_email in gh_user_cache:
                 main_user = gh_user_cache[most_user_email]
             else:

From 5c035132aaef7e4032e16daa0164e5a5ac61b175 Mon Sep 17 00:00:00 2001
From: mjh316 <61671361+mjh316@users.noreply.github.com>
Date: Fri, 31 Dec 2021 11:15:06 -0800
Subject: [PATCH 3/8] debug gitstamp

---
 source/_ext/gitstamp.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/source/_ext/gitstamp.py b/source/_ext/gitstamp.py
index ce64c1977..cef6aedc2 100644
--- a/source/_ext/gitstamp.py
+++ b/source/_ext/gitstamp.py
@@ -15,6 +15,8 @@
 from sphinx import errors
 from github import Github
 
+from sys import version_info
+print(version_info)
 # Gets the datestamp of the latest commit on the given file
 # Converts the datestamp into something more readable
 # Skips files whose datestamp we can't parse.
@@ -48,8 +50,11 @@ def page_context_handler(app, pagename, templatename, context, doctree):
         # Splits on newline to get the first (highest commits) contributor, then handles whitespace, then gets info
         most_commits, _most_user = g.git.shortlog('-sne', '--', ("%s.rst" % fullpagename)).split('\n')[0].strip().split('\t')
         # Parses all of 'first_name last_name <email>', 'first_name middle_name last_name <email>', and 'name <email>' correctly
-        most_user_name, most_user_email = ' '.join(_most_user.split(' ')[:-1]), _most_user.split(' ')[-1][1:-1]
-        
+        most_user_name = ' '.join(_most_user.split(' ')[:-1])
+        most_user_email = _most_user.split(' ')[-1][1:-1]
+
+        raise Exception(f'{most_commits} {_most_user} {most_user_name} {most_user_email}')
+    
         if not commits:
             # Don't datestamp generated rst's (e.g. imapd.conf.rst)
             # Ideally want to check their source - lib/imapoptions, etc, but

From 17dbe99d1996729f2aa551825383026d96b7df0f Mon Sep 17 00:00:00 2001
From: mjh316 <61671361+mjh316@users.noreply.github.com>
Date: Fri, 31 Dec 2021 11:19:23 -0800
Subject: [PATCH 4/8] debug git shortlog command in gitstamp

---
 source/_ext/gitstamp.py | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/source/_ext/gitstamp.py b/source/_ext/gitstamp.py
index cef6aedc2..878762540 100644
--- a/source/_ext/gitstamp.py
+++ b/source/_ext/gitstamp.py
@@ -48,12 +48,14 @@ def page_context_handler(app, pagename, templatename, context, doctree):
     try:
         commits = g.iter_commits('--all', max_count=1, paths="%s.rst" % fullpagename)
         # Splits on newline to get the first (highest commits) contributor, then handles whitespace, then gets info
-        most_commits, _most_user = g.git.shortlog('-sne', '--', ("%s.rst" % fullpagename)).split('\n')[0].strip().split('\t')
-        # Parses all of 'first_name last_name <email>', 'first_name middle_name last_name <email>', and 'name <email>' correctly
-        most_user_name = ' '.join(_most_user.split(' ')[:-1])
-        most_user_email = _most_user.split(' ')[-1][1:-1]
+        try:
+            most_commits, _most_user = g.git.shortlog('-sne', '--', ("%s.rst" % fullpagename)).split('\n')[0].strip().split('\t')
 
-        raise Exception(f'{most_commits} {_most_user} {most_user_name} {most_user_email}')
+        # Parses all of 'first_name last_name <email>', 'first_name middle_name last_name <email>', and 'name <email>' correctly
+            most_user_name = ' '.join(_most_user.split(' ')[:-1])
+            most_user_email = _most_user.split(' ')[-1][1:-1]
+        except Exception:
+            raise Exception(f"git shortlog: {g.git.shortlog('-sne', '--', ('%s.rst' % fullpagename)).split('\n')[0]}")
     
         if not commits:
             # Don't datestamp generated rst's (e.g. imapd.conf.rst)

From 0b73c7385505d855ee6b3a08bc208f26ea5c8787 Mon Sep 17 00:00:00 2001
From: mjh316 <61671361+mjh316@users.noreply.github.com>
Date: Fri, 31 Dec 2021 11:23:03 -0800
Subject: [PATCH 5/8] debugging print output for gitstamp

---
 source/_ext/gitstamp.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/source/_ext/gitstamp.py b/source/_ext/gitstamp.py
index 878762540..c9262d8c5 100644
--- a/source/_ext/gitstamp.py
+++ b/source/_ext/gitstamp.py
@@ -55,7 +55,8 @@ def page_context_handler(app, pagename, templatename, context, doctree):
             most_user_name = ' '.join(_most_user.split(' ')[:-1])
             most_user_email = _most_user.split(' ')[-1][1:-1]
         except Exception:
-            raise Exception(f"git shortlog: {g.git.shortlog('-sne', '--', ('%s.rst' % fullpagename)).split('\n')[0]}")
+            print(g.git.shortlog('-sne', '--', ('%s.rst' % fullpagename)).split('\n')[0])
+            raise Exception(g.git.shortlog('-sne', '--', ('%s.rst' % fullpagename)).split('\n')[0])
     
         if not commits:
             # Don't datestamp generated rst's (e.g. imapd.conf.rst)

From b5d027eeb183161263280109b40b5131c52a41d0 Mon Sep 17 00:00:00 2001
From: mjh316 <61671361+mjh316@users.noreply.github.com>
Date: Fri, 31 Dec 2021 11:34:00 -0800
Subject: [PATCH 6/8] fix empty shortlog

---
 source/_ext/gitstamp.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/source/_ext/gitstamp.py b/source/_ext/gitstamp.py
index c9262d8c5..f65e925cb 100644
--- a/source/_ext/gitstamp.py
+++ b/source/_ext/gitstamp.py
@@ -49,14 +49,15 @@ def page_context_handler(app, pagename, templatename, context, doctree):
         commits = g.iter_commits('--all', max_count=1, paths="%s.rst" % fullpagename)
         # Splits on newline to get the first (highest commits) contributor, then handles whitespace, then gets info
         try:
-            most_commits, _most_user = g.git.shortlog('-sne', '--', ("%s.rst" % fullpagename)).split('\n')[0].strip().split('\t')
+            most_commits, _most_user = ''
 
         # Parses all of 'first_name last_name <email>', 'first_name middle_name last_name <email>', and 'name <email>' correctly
             most_user_name = ' '.join(_most_user.split(' ')[:-1])
             most_user_email = _most_user.split(' ')[-1][1:-1]
-        except Exception:
-            print(g.git.shortlog('-sne', '--', ('%s.rst' % fullpagename)).split('\n')[0])
-            raise Exception(g.git.shortlog('-sne', '--', ('%s.rst' % fullpagename)).split('\n')[0])
+        except ValueError:
+            most_user_email = ''
+            most_user_name = ''
+            most_commits = ''
     
         if not commits:
             # Don't datestamp generated rst's (e.g. imapd.conf.rst)

From 3b4554588e7a97e215c9391b140a16eea79f73f4 Mon Sep 17 00:00:00 2001
From: mjh316 <61671361+mjh316@users.noreply.github.com>
Date: Fri, 31 Dec 2021 11:40:17 -0800
Subject: [PATCH 7/8] final fixed gitstamp error handling

---
 source/_ext/gitstamp.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/_ext/gitstamp.py b/source/_ext/gitstamp.py
index f65e925cb..b597de6cd 100644
--- a/source/_ext/gitstamp.py
+++ b/source/_ext/gitstamp.py
@@ -49,7 +49,7 @@ def page_context_handler(app, pagename, templatename, context, doctree):
         commits = g.iter_commits('--all', max_count=1, paths="%s.rst" % fullpagename)
         # Splits on newline to get the first (highest commits) contributor, then handles whitespace, then gets info
         try:
-            most_commits, _most_user = ''
+            most_commits, _most_user = g.git.shortlog('-sne', '--', ("%s.rst" % fullpagename)).split('\n')[0].strip().split('\t')
 
         # Parses all of 'first_name last_name <email>', 'first_name middle_name last_name <email>', and 'name <email>' correctly
             most_user_name = ' '.join(_most_user.split(' ')[:-1])

From cdd9bf6eb5f0dcfa609e56f528cffa6bb37ea90a Mon Sep 17 00:00:00 2001
From: mjh316 <61671361+mjh316@users.noreply.github.com>
Date: Fri, 31 Dec 2021 11:47:38 -0800
Subject: [PATCH 8/8] gitstamp debugging

---
 source/_ext/gitstamp.py               |  18 ++-
 source/_static/css/custom.css         |   4 +
 source/handbook/doc-common-tasks.rst  |  38 +++++
 source/handbook/doc-repos.rst         | 193 ++++++++++++++++++++++++
 source/handbook/doc-sphinx-primer.rst | 205 ++++++++++++++++++++++++++
 source/handbook/doc-workflow.rst      |  54 +++++++
 source/handbook/documenting.rst       | 196 ++----------------------
 source/handbook/index.rst             |   6 +-
 8 files changed, 522 insertions(+), 192 deletions(-)
 create mode 100644 source/handbook/doc-common-tasks.rst
 create mode 100644 source/handbook/doc-repos.rst
 create mode 100644 source/handbook/doc-sphinx-primer.rst
 create mode 100644 source/handbook/doc-workflow.rst

diff --git a/source/_ext/gitstamp.py b/source/_ext/gitstamp.py
index b7fb75512..b597de6cd 100644
--- a/source/_ext/gitstamp.py
+++ b/source/_ext/gitstamp.py
@@ -15,6 +15,8 @@
 from sphinx import errors
 from github import Github
 
+from sys import version_info
+print(version_info)
 # Gets the datestamp of the latest commit on the given file
 # Converts the datestamp into something more readable
 # Skips files whose datestamp we can't parse.
@@ -46,10 +48,17 @@ def page_context_handler(app, pagename, templatename, context, doctree):
     try:
         commits = g.iter_commits('--all', max_count=1, paths="%s.rst" % fullpagename)
         # Splits on newline to get the first (highest commits) contributor, then handles whitespace, then gets info
-        most_commits, _most_user = g.git.shortlog('-sne', '--', ("%s.rst" % fullpagename)).split('\n')[0].strip().split('\t')
+        try:
+            most_commits, _most_user = g.git.shortlog('-sne', '--', ("%s.rst" % fullpagename)).split('\n')[0].strip().split('\t')
+
         # Parses all of 'first_name last_name <email>', 'first_name middle_name last_name <email>', and 'name <email>' correctly
-        most_user_name, most_user_email = ' '.join(_most_user.split(' ')[:-1]), _most_user.split(' ')[-1][1:-1]
-        
+            most_user_name = ' '.join(_most_user.split(' ')[:-1])
+            most_user_email = _most_user.split(' ')[-1][1:-1]
+        except ValueError:
+            most_user_email = ''
+            most_user_name = ''
+            most_commits = ''
+    
         if not commits:
             # Don't datestamp generated rst's (e.g. imapd.conf.rst)
             # Ideally want to check their source - lib/imapoptions, etc, but
@@ -58,7 +67,6 @@ def page_context_handler(app, pagename, templatename, context, doctree):
 
         commit = next(iter(commits))
         context['gitstamp'] = datetime.datetime.fromtimestamp(commit.authored_date).strftime("%Y&#8209;%m&#8209;%d")
-        #raise Exception(f'{commit.author.email} \n {most_user_name, most_user_email}')
 
         last_user = GHCachedUser(commit.author.name)
         main_user = GHCachedUser(most_user_name)
@@ -84,7 +92,7 @@ def page_context_handler(app, pagename, templatename, context, doctree):
                         last_user.avatar_url = gh_commit.author.avatar_url
 
                 gh_user_cache[commit.author.email] = last_user
-            # Repeat above for most user
+            # Repeat above for main_user
             if most_user_email in gh_user_cache:
                 main_user = gh_user_cache[most_user_email]
             else:
diff --git a/source/_static/css/custom.css b/source/_static/css/custom.css
index ab8e9346a..e253f106c 100644
--- a/source/_static/css/custom.css
+++ b/source/_static/css/custom.css
@@ -951,6 +951,10 @@ img.no-background {
     background-color: transparent;
 }
 
+.highlight .gh {
+    color: #27c5f3;
+}
+
 .warning {
     border-left: 6px solid red;
     background-color: 251B34;
diff --git a/source/handbook/doc-common-tasks.rst b/source/handbook/doc-common-tasks.rst
new file mode 100644
index 000000000..b5ccc4d79
--- /dev/null
+++ b/source/handbook/doc-common-tasks.rst
@@ -0,0 +1,38 @@
+############
+Common tasks
+############
+
+These are little how-to guides for some common tasks, in no particular order:
+
+Update the property tables
+==========================
+
+The `network <https://docs.symbolplatform.com/guides/network/configuring-network-properties.html>`__ and `node <https://docs.symbolplatform.com/guides/network/configuring-node-properties.html>`__ pages contain `static HTML snippets <https://github.com/symbol/symbol-docs/tree/main/source/_static>`__ autogenerated from the Catapult source code and Bootstrap's config files.
+
+The generation code is in the `catapult-docs-cli <https://github.com/symbol/catapult-docs-cli>`__ repository and you will need to use the ``properties`` command.
+
+`The README <https://github.com/symbol/catapult-docs-cli/blob/master/README.md>`__ already contains a section on how to generate these tables.
+
+Whenever one of the default property values changes you will need to update the tables and commit the resulting HTML files in the ``symbol-docs`` repository.
+
+Update the serialization tables
+===============================
+
+The `serialization <https://docs.symbolplatform.com/serialization/index.html>`__ tables are also autogenerated using the `catapult-docs-cli <https://github.com/symbol/catapult-docs-cli>`__ repository, using the ``serialization`` command.
+
+`The README <https://github.com/symbol/catapult-docs-cli/blob/master/README.md>`__ already contains a section on how to generate these tables.
+
+The ``serialization`` command will generate a standalone HTML file for each structure and a single ``.rst`` or ``.md`` file including all of them to be used as the Serialization page in the docs. The command already puts the files in their proper place in the ``symbol-docs`` folder.
+
+The individual HTML files can be included in any doc page using the ``.. serializationref::`` directive.
+
+.. _doc-redirections:
+
+Redirections
+============
+
+Whenever you rename or remove an existing doc page chances are you are breaking somebody's link to the docs. To avoid this, leave a **Redirect** in place.
+
+The `redirects <https://github.com/symbol/symbol-docs/blob/main/source/redirects>`__ file in the ``source`` folder contains a list of pairs "old-name new-name", separated by a space. In the build process, Sphinx will create HTML files for all "old-names" which contain a redirect to the "new-name".
+
+.. caution:: The path to the new name is still a mystery to me. It seems to be relative to the location of the "old-name", but you need to go up a directory and then down again. **Test thoroughly**, both locally and once deployed.
\ No newline at end of file
diff --git a/source/handbook/doc-repos.rst b/source/handbook/doc-repos.rst
new file mode 100644
index 000000000..47ed2671c
--- /dev/null
+++ b/source/handbook/doc-repos.rst
@@ -0,0 +1,193 @@
+####################
+Repository structure
+####################
+
+There are currently 3 sources of documentation for Symbol. Feel free to jump to the one you are interested in.
+
+- `Technical documentation <#technical-documentation>`__: Tool guides, developer tutorials, SDK reference guides and the Syndicate's handbook.
+- `NEM NIS1 documentation <#nis1-documentation>`__: Old NEM NIS1 guides, pending assimilation into the Symbol technical docs.
+- `Working documentation <#working-documentation>`__: Meeting minutes, Community logs, stuff that changes often.
+
+Technical documentation
+***********************
+
+.. csv-table::
+    :delim: ;
+    :widths: 30 70
+    :class: docs-repo-table
+
+    **Site** ; `docs.symbolplatform.com <https://docs.symbolplatform.com>`__
+    **Source repo** ; `github.com/symbol/symbol-docs <https://github.com/symbol/symbol-docs>`__
+    **Host** ; `GitHub pages <https://github.com/symbol/symbol.github.io>`__
+    **Engine** ; `Sphinx <https://www.sphinx-doc.org>`__
+    **Format** ; `reStructuredText <https://docutils.sourceforge.io/rst.html>`__
+    **Intended readers** ; The world at large.
+    **Intended writers** ; The Symbol technical writers.
+    **Editing workflow** ; Git-based: Check out the source repository, make modifications, check results by building the pages locally and submit pull requests.
+    **Localization** ; `Transifex <https://www.transifex.com/nemtech/symboldocs/>`__
+    **Maintainers** ; `Xavi <https://github.com/segfaultxavi>`__
+
+Content
+-------
+
+This is the main technical reference for **Symbol**. It contains (or will contain):
+
+- **User guides** for the different tools (Wallet, CLI, Explorer, etc.), intended for non-heavily-technical readers, including screenshots and step-by-step instructions on how to solve common problems.
+- **Developer tutorials** with source code examples in different languages, organized by topics. Ranging from Getting Started to in-depth guides on specific topics.
+- **Concept definitions** required to understand the Symbol protocol.
+- **Technical reference** guides describing every API and REST endpoint.
+
+Due to the complexity of the technical content, the `Sphinx <https://www.sphinx-doc.org>`__ engine and `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ is used instead of the simpler MarkDown format. This enables much more flexibility, so we can use multi-language (tabbed) code snippets, Python macros which automatically retrieve content from GitHub or have more formatting options for complex tables, for example.
+
+Editing
+-------
+
+This repository follows the docs-as-code approach, meaning that you treat the documentation as if it was source code.
+
+To contribute you need to check out the Git repository, make your changes and submit a `Pull Request <https://docs.github.com/en/github/collaborating-with-pull-requests>`__ to GitHub. The repository maintainers will review your contribution, suggest changes if required and eventually merge it.
+
+Testing locally
+---------------
+
+Before submitting a pull request it is a good idea to test your changes locally, to ensure that everything shows as expected and nothing breaks.
+
+You first need to `Install Sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`__. Basically, you need to:
+
+- Install Python 3.7
+- Run ``pip install -r requirements.txt``
+
+After that you can trigger a build by running from the repository's root:
+
+.. code-block:: bash
+
+    make livehtml
+
+This generates all HTML files in the ``build/html`` folder, including all assets like images, javascript, CSS, code snippets, etc. This also monitors your source folder and regenerates the output when changes are detected. It also instantiates a web server on ``localhost:8000`` for your convenience.
+
+.. note::
+
+    On Windows you have a handy ``make-win.bat`` that does the same thing but takes care of some Windows shenanigans like incorrect console output and filesystem monitoring.
+
+Deployment
+----------
+
+The GitHub repository is linked to `Travis <https://travis-ci.com/github/symbol/symbol-docs>`__, so on every push to the ``main`` branch a full build is triggered (See ``.travis.yml`` and the ``travis`` folder for details). This involves several steps besides the generation of the output documentation:
+
+- **Source snippets validation**: The guides include lots of source code examples which are actually snippets from complete programs. These programs must **compile** and pass **lint checks** at all times and Travis makes sure of this. Right now only the TypeScript programs are checked.
+- **Link checking**: All pages are examined to find broken links using ``make linkcheck``.
+
+  Throttling is enabled to avoid pestering servers too much and getting ``HTTP 429 Too Many Requests`` errors. Still, sometimes your build fails because of this. If you detect such error in the Travis logs just try again.
+
+  If you are sure a link is correct but linkcheck on Travis keeps failing, you can add this particular link to the ``linkcheck_ignore`` list in ``conf.py`` to skip checking it. Please add a comment explaining the reason.
+- **Localization**: Text strings are extracted from every page using ``make gettext`` and uploaded to Transifex (see next section).
+- **Publishing**: The built HTML pages are moved to the ``docs`` folder in the ``gh-pages`` branch and pushed. GitHub pages is configured to serve them from there.
+
+Due to this process, pushes to ``main`` normally take up to 5 minutes to go live.
+
+Localization
+------------
+
+Right now almost every page is available in Japanese besides the original English, but the repository is ready to accept more languages.
+
+`Transifex <https://www.transifex.com/nemtech/symboldocs/>`__ is integrated in the deployment process, so after every push to ``main`` Travis extracts and sends all strings (``.pot`` files) to Transifex, which detects any new or updated text and notifies the translators.
+
+Translators can log in to Transifex and provide the translations there. Developers can then download the updated text (``.po`` files) and commit them to the source repository.
+
+So far this process has been entirely done by the Symbol community, even committing the updated texts and submitting pull requests.
+
+NEM NIS1 documentation
+**********************
+
+.. csv-table::
+    :delim: ;
+    :widths: 30 70
+    :class: table-double-rows docs-repo-table
+
+    **Site** ; **Docs**: `nemproject.github.io/nem-docs <https://nemproject.github.io/nem-docs>`__
+    ;**API**: `nemproject.github.io <https://nemproject.github.io/>`__
+    **Source repo** ; **Docs**: `github.com/NemProject/nem-docs <https://github.com/NemProject/nem-docs/tree/gh-pages>`__ (``gh-pages`` branch)
+    ;**API**: `https://github.com/NemProject/NemProject.github.io <https://github.com/NemProject/NemProject.github.io>`__
+    **Host** ; **Docs**: `GitHub pages <https://github.com/NemProject/nem-docs/tree/gh-pages>`__
+    ;**API**: `GitHub pages <https://github.com/NemProject/NemProject.github.io>`__
+    **Engine** ; **Docs**: `GitHub Jekyll <https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll>`__
+    ;**API**: Static HTML page
+    **Format** ; **Docs**: `Markdown <https://www.markdownguide.org/>`__
+    ;**API**: HTML
+    **Intended readers** ; The world at large.
+    ;
+    **Intended writers** ; The Symbol technical writers.
+    ;
+    **Editing workflow** ; Git-based: Check out the source repository, make modifications, check results by building the pages locally and submit pull requests.
+    ;
+    **Localization** ; None
+    ;
+    **Maintainers** ; `Xavi <https://github.com/segfaultxavi>`__
+
+Content
+-------
+
+These are the old NEM NIS1 docs, which were spread over several repos, blogs and forum posts, ported over a to single repository. This documentation is rather old and parts of it are still being figured out.
+
+The old docs were mainly hosted at ``docs.nem.io`` from the `github.com/saulgray/nemioDev <https://github.com/saulgray/nemioDev>`__ repository using the `Grav Engine <https://getgrav.org/>`__.
+
+A much simpler GitHub page is setup now, using the `Jekyll Engine <https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll>`__ provided by GitHub, using plain Markdown. All content is in the ``gh-pages`` branch.
+
+.. note:: There is still some placeholders left in the docs (like `the overview page <https://nemproject.github.io/nem-docs/pages/Overview/docs.en.html>`__) so a big **PREVIEW** banner is shown at the top of every page.
+
+    This banner is `hardcoded in the layout HTML file <https://github.com/NemProject/nem-docs/blob/gh-pages/_layouts/default.html#L45>`__ and can be removed once the docs are good to go public.
+
+Editing
+-------
+
+This repository follows the docs-as-code approach, meaning that you treat the documentation as if it was source code.
+
+To contribute you need to check out the Git repository, make your changes and submit a `Pull Request <https://docs.github.com/en/github/collaborating-with-pull-requests>`__ to GitHub. The repository maintainers will review your contribution, suggest changes if required and eventually merge it.
+
+Testing locally
+---------------
+
+Before submitting a pull request it is a good idea to test your changes locally, to ensure that everything shows as expected and nothing breaks.
+
+Follow `GitHub's instructions <https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll>`__ to install a local Jekyll instance and run it.
+
+Deployment
+----------
+
+Deployment is straightforward since a standard GitHub pages setup is used (GitHub repo + Jekyll site + GitHub pages). Just push to the ``gh-pages`` branch and it will be published in seconds.
+
+Working documentation
+*********************
+
+.. csv-table::
+    :delim: ;
+    :widths: 30 70
+    :class: docs-repo-table
+
+    **Site** ; `hackmd.io/team/syndicate <https://hackmd.io/team/syndicate>`__
+    **Source repo** ; `hackmd.io/team/syndicate <https://hackmd.io/team/syndicate>`__
+    **Host** ; `hackmd.io/team/syndicate <https://hackmd.io/team/syndicate>`__
+    **Engine** ; HackMD
+    **Format** ; `Markdown <https://www.markdownguide.org/>`__
+    **Intended readers** ; Syndicate members.
+    **Intended writers** ; Syndicate members.
+    **Editing workflow** ; Edit pages directly on HackMD.
+    **Localization** ; None
+    **Maintainers** ; Every syndicate member.
+
+This is meant as a scratch pad for collaborative editing, or as a means of storage for documents that change too often or are too big or numerous to be in the Handbook.
+
+Examples are:
+
+- Documents being worked on (they are live, or waiting approval to go into the Handbook)
+- Meeting minutes (there are too many of them)
+- Test results (they change continuously)
+
+To keep this area organized all documents should be **tagged**. Please add this line at the bottom of your document:
+
+.. code-block::
+
+   ###### tags: `tag1` `tag2`
+
+Use any tag you want, but please look at the other documents and try to be consistent.
+
+.. caution:: If you don't use a tag your document will appear in the **Untagged** section and you will be severely reprimanded.
diff --git a/source/handbook/doc-sphinx-primer.rst b/source/handbook/doc-sphinx-primer.rst
new file mode 100644
index 000000000..f370e31d7
--- /dev/null
+++ b/source/handbook/doc-sphinx-primer.rst
@@ -0,0 +1,205 @@
+#############
+Sphinx primer
+#############
+
+The Symbol documentation pages are made with `Sphinx <https://www.sphinx-doc.org>`__, a documentation engine built around the `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ format and adding its own extensions.
+
+Therefore, you will need to read both the RST and `Sphinx <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__ docs to learn about their syntax. This page is intended as an extremely quick summary of the things you will most commonly use.
+
+It is extremely helpful to use an IDE that supports reStructuredText, like `Visual Studio Code <https://code.visualstudio.com/>`__ with an `RST extension <https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext>`__, for example.
+
+.. note:: Pay attention to Sphinx's log output when building! Any warning you see there is worth investigating.
+
+Basic formatting
+================
+
+- **Bold**: \*\*Bold\*\*
+- *Italics*: \*Italics\*
+- ``Monospace``: \`\`Monospace\`\`
+- Unordered lists: Start items with - or \*.
+- Ordered lists: Start items with numbers or #.
+- Headers: Underline (and optionally overline) the header with any of the characters #, \*, =, -, ^ or ". The level of the header will be inferred from the order in which they are found. The Symbol docs mostly use only 3 levels indicated with the characters #, \* and =.
+
+  .. code-block:: rst
+
+     ##########
+     Main Title
+     ##########
+
+     First Section
+     =============
+
+     Normal text.
+
+- Quoted block: Indent with a space. **Indentation is critical in RST!**
+- Code blocks: See the directives section below.
+
+Links
+=====
+
+- External link: Enclosed in backticks, with a trailing **double underscore**.
+
+  .. code-block:: rst
+
+     `Link Title <link-url>`__
+
+- Internal link to another page:
+
+  .. code-block:: rst
+
+     :doc:`Link Title <relative-file-path-without-extension>`
+
+  The path is relative to the current file, or absolute (from the ``source`` directory) if it starts with ``/``.
+
+  You can skip the Link Title part and use the document's actual title (its first header):
+
+  .. code-block:: rst
+
+     :doc:`relative-file-path-without-extension`
+
+- Internal link to a label (anchor):
+
+  .. code-block:: rst
+
+     :ref:`Link Title <label-name>`
+
+  And define labels (in any file) like this:
+
+  .. code-block:: rst
+
+     .. _label-name:
+
+     Here comes a new section
+     ========================
+
+  If the label appears right before a header (as in the example above), you can omit the "Link Title" part in the link and the header text will be used:
+
+  .. code-block:: rst
+
+     :ref:`label-name`
+
+Tables
+======
+
+There are `different mechanisms <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives>`__ to render tables in Sphinx. The most used in the Symbol docs is the `csv-table <https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table>`__:
+
+.. code-block:: rst
+
+   .. csv-table::
+      :header: "Header 1", "Header 2", "Header 3"
+      :widths: 25 25 50
+      :delim: ;
+
+      Data 1; Data 2; Data 3
+      Data 4; Data 5; Data 6
+
+``:header:``, ``:widths:`` and ``:delim:`` are optional and do not require much explanation. ``:delim:`` indicates the character used to separate columns in the data that follows.
+
+Note that the data is indented so it is aligned with the word ``csv-table`` (i.e. indented by 3 spaces).
+
+Adding pages
+============
+
+In the Symbol docs all pages appear in the Navigation bar at the left, therefore all pages **must appear in a TOC tree**. Any page can indicate what other pages are its children by using the ``toctree`` directive (you can search for examples in the current docs).
+
+If you add a new page, besides creating the ``.rst`` file in the proper folder, you will need to add its name to the ``toctree`` of its parent:
+
+.. code-block:: rst
+
+   .. toctree::
+       :maxdepth: 1
+
+       doc-repos
+       doc-workflow
+       doc-sphinx-primer
+       doc-common-tasks
+
+``:maxdepth: 1`` indicates that you do not want that page's sections or its sub-pages to be listed. If the page has sub-pages you will give it its own ``toctree`` so they are shown.
+
+You can add ``:hidden:`` so the list of pages does not render on the page. It will still show up in the navigation bar.
+
+Substitutions
+=============
+
+Sphinx allows defining some codewords to be substituted by longer text. The codewords are indicated between pipe characters ``|like-this|`` and can be defined anywhere. In the Symbol docs they are mostly defined in the ``conf.py`` file (In the ``rst_prolog`` variable).
+
+The most commonly used substitution is ``|codename|`` which expands to "|codename|". `There is an open issue to remove this particular one <https://github.com/symbol/symbol-docs/issues/670>`__.
+
+Useful directives
+=================
+
+Directives have the form ``.. directive-name::`` and are a mechanism to extend RST functionality. Sphinx added its own directives over RST, and the Symbol docs further add a few more (Look at the ``/source/_ext`` folder. They are written in Python).
+
+Directives can have an unnamed parameter **after** the directive name (see ``code-block`` below), or multiple named parameters between colons ``:`` in the lines below (as you have seen above in the Tables section).
+
+The directive **body** is separated from the directive and parameters by a blank line and is indented by 3 spaces.
+
+These are the most commonly used directives in the Symbol docs (besides the ones already mentioned):
+
+- ``code-block``: To insert syntax-highlighted code.
+
+  .. code-block:: rst
+
+     .. code-block:: language
+
+        code
+
+- ``figure``: To insert a captioned image.
+
+  .. code-block:: rst
+
+     .. figure:: image-file-path
+
+        Caption text.
+
+- ``note``, ``caution``, ``topic``: To insert a titled, colored box (notes are blue, cautions are orange). Topics allow defining your own title, otherwise it will be "Note" or "Caution".
+
+  .. code-block:: rst
+
+     .. note:: Some text
+
+        Some more text.
+
+- ``raw``: To insert raw HTML. Use only in case of emergency.
+
+  .. code-block:: rst
+
+     .. raw:: html
+
+        HTML code.
+
+- ``tabs``: Define tabbed content.
+
+  .. code-block:: rst
+
+     .. tabs::
+
+        .. tab:: Tab1 title
+
+           Tab1 content
+
+        .. tab:: Tab2 title
+
+           Tab2 content
+
+- ``example-code``: Tabbed source code, with syntax highlight and link to original source file.
+
+  .. code-block:: rst
+
+     .. example-code::
+
+        .. viewsource:: ../resources/examples/typescript/transfer/DefiningMaxFee.ts
+            :language: typescript
+            :start-after: /* start block 01 */
+            :end-before: /* end block 01 */
+
+        .. viewsource:: ../resources/examples/typescript/transfer/DefiningMaxFee.js
+            :language: javascript
+            :start-after: /* start block 01 */
+            :end-before: /* end block 01 */
+
+- ``serializationref``: Inserts nicely-formatted serialization documentation.
+
+  .. code-block:: rest
+
+     .. serializationref:: StructureName
diff --git a/source/handbook/doc-workflow.rst b/source/handbook/doc-workflow.rst
new file mode 100644
index 000000000..016bd0f7f
--- /dev/null
+++ b/source/handbook/doc-workflow.rst
@@ -0,0 +1,54 @@
+######################
+Documentation workflow
+######################
+
+The project board
+=================
+
+There is a GitHub project board (a regular `Kanban <https://en.wikipedia.org/wiki/Kanban>`__ board) keeping all pending **issues** organized: https://github.com/orgs/symbol/projects/8
+
+Every GitHub issue assigned to the ``Documentation`` project goes to this board. Then you can drag & drop cards around to keep track of their progress until the tasks are done.
+
+Only GitHub **issues** go to this board, not **Pull Requests**. When a PR is created to fix an issue, it should be linked to it but not be added to the ``Documentation`` project so that it does not show on the board.
+
+The columns are:
+
+- **Backlog**: Pending tasks. All new issues go to this column. You can create issues, but also anybody else in the world. Creating issues is actually encouraged by the link at the bottom of every doc page ("Give us your feedback").
+- **Priority**: These are the tasks that should be worked on next. When you finish a task you should come to this column and start working on the task at the top.
+- **In progress**: Tasks currently being worked on. The purpose of this column is to keep everybody informed on what you are currently working on.
+- **Revision**: Finished tasks pending review or approval. Who should approve depends on the task and who created it.
+- **Done**: Finished tasks. Typically issues are automatically closed when their linked PR is merged, and the issue moves automatically to the Done column.
+
+Periodically (once a week?) you should review the **Priority** list, move cards to make sure the list is still current, and touch base with the Captains.
+
+Issue labels
+============
+
+Issues are labelled for easier organization. These are the main labels:
+
+- Errors
+
+  - ``P1``: Information is wrong. This should be fixed ASAP.
+  - ``P2``: Information is incomplete.
+  - ``P3``: Aesthetic issues.
+
+- Suggestions
+
+  - ``enhancement``: Generic label for things that can be improved.
+  - ``good first issue``: Simple tasks good for getting acquainted with the system. **Newcomers should start with these ones**.
+
+Use the filter box in the project board to show only issues with a given label, like ``label:"good first issue"`` `for example <https://github.com/orgs/symbol/projects/8?card_filter_query=label%3A%22good+first+issue%22>`_.
+
+Local testing
+=============
+
+The :doc:`doc-repos` document explains how to test your changes locally before pushing any changes to GitHub.
+
+PR previews
+===========
+
+Every Pull Request generates a preview using `Netlify <https://app.netlify.com/sites/nemtech/overview>`__. The ``netlify`` bot will add a comment to the PR with links to the preview build status and results.
+
+Use these previews to ensure the build works fine and to share the results with the team.
+
+.. note:: Some features work differently on the preview, like :ref:`doc-redirections` or the site's favicon. If something does not work and you cannot find why, maybe it's worth doing the real deployment (pushing to the ``main`` branch) and observe the results.
\ No newline at end of file
diff --git a/source/handbook/documenting.rst b/source/handbook/documenting.rst
index faa415ab9..af208b746 100644
--- a/source/handbook/documenting.rst
+++ b/source/handbook/documenting.rst
@@ -1,189 +1,13 @@
-##########################
-Contributing documentation
-##########################
+#############
+Documentation
+#############
 
-There are currently 3 sources of documentation for Symbol. Feel free to jump to the one you are interested in.
+Documentation topics to help you maintain the Symbol docs.
 
-- `Technical documentation <#technical-documentation>`__: Tool guides, developer tutorials, SDK reference guides and the Syndicate's handbook.
-- `NEM NIS1 documentation <#nis1-documentation>`__: Old NEM NIS1 guides, pending assimilation into the Symbol technical docs.
-- `Working documentation <#working-documentation>`__: Meeting minutes, Community logs, stuff that changes often.
+.. toctree::
+    :maxdepth: 1
 
-Technical documentation
-***********************
-
-.. csv-table::
-    :delim: ;
-    :widths: 30 70
-    :class: docs-repo-table
-
-    **Site** ; `docs.symbolplatform.com <https://docs.symbolplatform.com>`__
-    **Source repo** ; `github.com/symbol/symbol-docs <https://github.com/symbol/symbol-docs>`__
-    **Host** ; `GitHub pages <https://github.com/symbol/symbol.github.io>`__
-    **Engine** ; `Sphinx <https://www.sphinx-doc.org>`__
-    **Format** ; `reStructuredText <https://docutils.sourceforge.io/rst.html>`__
-    **Intended readers** ; The world at large.
-    **Intended writers** ; The Symbol technical writers.
-    **Editing workflow** ; Git-based: Check out the source repository, make modifications, check results by building the pages locally and submit pull requests.
-    **Localization** ; `Transifex <https://www.transifex.com/nemtech/symboldocs/>`__
-    **Maintainers** ; `Xavi <https://github.com/segfaultxavi>`__
-
-Content
--------
-
-This is the main technical reference for **Symbol**. It contains (or will contain):
-
-- **User guides** for the different tools (Wallet, CLI, Explorer, etc.), intended for non-heavily-technical readers, including screenshots and step-by-step instructions on how to solve common problems.
-- **Developer tutorials** with source code examples in different languages, organized by topics. Ranging from Getting Started to in-depth guides on specific topics.
-- **Concept definitions** required to understand the Symbol protocol.
-- **Technical reference** guides describing every API and REST endpoint.
-
-Due to the complexity of the technical content, the `Sphinx <https://www.sphinx-doc.org>`__ engine and `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ is used instead of the simpler MarkDown format. This enables much more flexibility, so we can use multi-language (tabbed) code snippets, Python macros which automatically retrieve content from GitHub or have more formatting options for complex tables, for example.
-
-Editing
--------
-
-This repository follows the doc-as-code approach, meaning that you treat the documentation as if it was source code.
-
-To contribute you need to check out the Git repository, make your changes and submit a `Pull Request <https://docs.github.com/en/github/collaborating-with-pull-requests>`__ to GitHub. The repository maintainers will review your contribution, suggest changes if required and eventually merge it.
-
-Testing locally
----------------
-
-Before submitting a pull request it is a good idea to test your changes locally, to ensure that everything shows as expected and nothing breaks.
-
-You first need to `Install Sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`__. Basically, you need to:
-
-- Install Python 3.7
-- Run ``pip install -r requirements.txt``
-
-After that you can trigger a build by running from the repository's root:
-
-.. code-block:: bash
-
-    make livehtml
-
-This generates all HTML files in the ``build/html`` folder, including all assets like images, javascript, CSS, code snippets, etc. This also monitors your source folder and regenerates the output when changes are detected. It also instantiates a web server on ``localhost:8000`` for your convenience.
-
-.. note::
-
-    On Windows you have a handy ``make-win.bat`` that does the same thing but takes care of some Windows shenanigans like incorrect console output and filesystem monitoring.
-
-Deployment
-----------
-
-The GitHub repository is linked to `Travis <https://travis-ci.com/github/symbol/symbol-docs>`__, so on every push to the ``main`` branch a full build is triggered (See ``.travis.yml`` and the ``travis`` folder for details). This involves several steps besides the generation of the output documentation:
-
-- **Source snippets validation**: The guides include lots of source code examples which are actually snippets from complete programs. These programs must **compile** and pass **lint checks** at all times and Travis makes sure of this. Right now only the TypeScript programs are checked.
-- **Link checking**: All pages are examined to find broken links using ``make linkcheck``. Throttling is enabled to avoid pestering servers too much and getting ``HTTP 429 Too Many Requests`` errors. Still, sometimes your build fails because of this. If you detect such error in the Travis logs just try again.
-- **Localization**: Text strings are extracted from every page using ``make gettext`` and uploaded to Transifex (see next section).
-- **Publishing**: The built HTML pages are moved to the ``docs`` folder in the ``gh-pages`` branch and pushed. GitHub pages is configured to serve them from there.
-
-Due to this process, pushes to ``main`` normally take up to 5 minutes to go live.
-
-Localization
-------------
-
-Right now almost every page is available in Japanese besides the original English, but the repository is ready to accept more languages.
-
-`Transifex <https://www.transifex.com/nemtech/symboldocs/>`__ is integrated in the deployment process, so after every push to ``main`` Travis extracts and sends all strings (``.pot`` files) to Transifex, which detects any new or updated text and notifies the translators.
-
-Translators can log in to Transifex and provide the translations there. Developers can then download the updated text (``.po`` files) and commit them to the source repository.
-
-So far this process has been entirely done by the Symbol community, even committing the updated texts and submitting pull requests.
-
-NEM NIS1 documentation
-**********************
-
-.. csv-table::
-    :delim: ;
-    :widths: 30 70
-    :class: table-double-rows docs-repo-table
-
-    **Site** ; **Docs**: `nemproject.github.io/nem-docs <https://nemproject.github.io/nem-docs>`__
-    ;**API**: `nemproject.github.io <https://nemproject.github.io/>`__
-    **Source repo** ; **Docs**: `github.com/NemProject/nem-docs <https://github.com/NemProject/nem-docs/tree/gh-pages>`__ (``gh-pages`` branch)
-    ;**API**: `https://github.com/NemProject/NemProject.github.io <https://github.com/NemProject/NemProject.github.io>`__
-    **Host** ; **Docs**: `GitHub pages <https://github.com/NemProject/nem-docs/tree/gh-pages>`__
-    ;**API**: `GitHub pages <https://github.com/NemProject/NemProject.github.io>`__
-    **Engine** ; **Docs**: `GitHub Jekyll <https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll>`__
-    ;**API**: Static HTML page
-    **Format** ; **Docs**: `Markdown <https://www.markdownguide.org/>`__
-    ;**API**: HTML
-    **Intended readers** ; The world at large.
-    ;
-    **Intended writers** ; The Symbol technical writers.
-    ;
-    **Editing workflow** ; Git-based: Check out the source repository, make modifications, check results by building the pages locally and submit pull requests.
-    ;
-    **Localization** ; None
-    ;
-    **Maintainers** ; `Xavi <https://github.com/segfaultxavi>`__
-
-Content
--------
-
-These are the old NEM NIS1 docs, which were spread over several repos and blog posts, ported over a to single repository. This documentation is rather old and parts of it are still being figured out.
-
-The old docs were mainly hosted at ``docs.nem.io`` from the `github.com/saulgray/nemioDev <https://github.com/saulgray/nemioDev>`__ repository using the `Grav Engine <https://getgrav.org/>`__.
-
-A much simpler GitHub page is setup now, using the `Jekyll Engine <https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll>`__ provided by GitHub, using plain Markdown. All content is in the ``gh-pages`` branch.
-
-.. note:: There is still some placeholders left in the docs (like `the overview page <https://nemproject.github.io/nem-docs/pages/Overview/docs.en.html>`__) so a big **PREVIEW** banner is shown at the top of every page.
-
-    This banner is `hardcoded in the layout HTML file <https://github.com/NemProject/nem-docs/blob/gh-pages/_layouts/default.html#L45>`__ and can be removed once the docs are good to go public.
-
-Editing
--------
-
-This repository follows the doc-as-code approach, meaning that you treat the documentation as if it was source code.
-
-To contribute you need to check out the Git repository, make your changes and submit a `Pull Request <https://docs.github.com/en/github/collaborating-with-pull-requests>`__ to GitHub. The repository maintainers will review your contribution, suggest changes if required and eventually merge it.
-
-Testing locally
----------------
-
-Before submitting a pull request it is a good idea to test your changes locally, to ensure that everything shows as expected and nothing breaks.
-
-Follow `GitHub's instructions <https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll>`__ to install a local Jekyll instance and run it.
-
-Deployment
-----------
-
-Deployment is straightforward since a standard GitHub pages setup is used (GitHub repo + Jekyll site + GitHub pages). Just push to the ``gh-pages`` branch and it will be published in seconds.
-
-Working documentation
-*********************
-
-.. csv-table::
-    :delim: ;
-    :widths: 30 70
-    :class: docs-repo-table
-
-    **Site** ; `hackmd.io/team/syndicate <https://hackmd.io/team/syndicate>`__
-    **Source repo** ; `hackmd.io/team/syndicate <https://hackmd.io/team/syndicate>`__
-    **Host** ; `hackmd.io/team/syndicate <https://hackmd.io/team/syndicate>`__
-    **Engine** ; HackMD
-    **Format** ; `Markdown <https://www.markdownguide.org/>`__
-    **Intended readers** ; Syndicate members.
-    **Intended writers** ; Syndicate members.
-    **Editing workflow** ; Edit pages directly on HackMD.
-    **Localization** ; None
-    **Maintainers** ; Every syndicate member.
-
-This is meant as a scratch pad for collaborative editing, or as a means of storage for documents that change too often or are too big or numerous to be in the Handbook.
-
-Examples are:
-
-- Documents being worked on (they are live, or waiting approval to go into the Handbook)
-- Meeting minutes (there are too many of them)
-- Test results (they change continuously)
-
-To keep this area organized all documents should be **tagged**. Please add this line at the bottom of your document:
-
-.. code-block::
-
-   ###### tags: `tag1` `tag2`
-
-Use any tag you want, but please look at the other documents and try to be consistent.
-
-.. caution:: If you don't use a tag your document will appear in the **Untagged** section and you will be severely reprimanded.
+    doc-repos
+    doc-workflow
+    doc-sphinx-primer
+    doc-common-tasks
diff --git a/source/handbook/index.rst b/source/handbook/index.rst
index b60029bdc..d4834366c 100644
--- a/source/handbook/index.rst
+++ b/source/handbook/index.rst
@@ -6,7 +6,11 @@ The Symbol Handbook
     :align: center
     :class: no-background
 
-    Welcome to the Symbol Syndicate's pirate handbook!
+    **Welcome to the Symbol Syndicate's pirate handbook!**
+
+This section of the documentation is intended for Syndicate employees, to help onboard the **new recruits** and keep a central **best practices repository**.
+
+It is still work-in-progress and is roughly divided into the following categories:
 
 **Philosophy**