This blog is all about your personal notes in Confluence. If you document your personal notes on Confluence you can improve the documentation, be organized well and be able to share your personal notes easily.

• Why should I use the Confluence personal space?
• What belongs into the personal space?
• What does not belong into the personal space?
• How do I set up and share my personal space with others?

These are the questions that I will try to answer here. Short answer: Improve your organization of personal notes!
If you don’t use it yet, it will hopefully improve your documentation. If you are already a user of the Confluence personal space you might get some new aspects. And if you already use it please comment, so I can learn from your experience!

The Problem with Personal Notes

I often find myself copying bash snippets from the internal project documentation or the internet. Most likely, I need to adapt some parts of it to fit my needs. And even more likely I need to do this regularly. Naturally I started a .txt document that contained the commands that I needed regularly. I couldn’t move these commands into the project space because these commands contained Universally Unique Identifiers (UUID) from my devices, my personal directory setup and similar customizations. However, I also found myself often to copy these commands and send them over to my team collegues. Until that day when one team collegue sent me a link to his personal Confluence space.

Personal Notes in the Confluence Personal Space

The personal space of the team collegue contain a list where he had his own collection of commands. That was the moment I startet to move all my commands to my own Confluence space.

You can even start a free plan for your private personal notes: Confluence Free

My Personal Space

My Confluence personal space at work currently looks like this:

• Nicolas Landing Page
  • Backend Stuff
  • Git Stuff
  • Linux Stuff
  • Microsoft Stuff
  • Project Stuff
  • Testsetup Stuff
• Temp Project Page1
• Temp Project Page2

Note how Confluence will sort these pages automatically if you don’t add a number in front. For me, this is just fine.

Example Page Content

Nicolas Landing Page

My personal space starts with a landing page. On this page I list links that I (currently) often need. I perfer to save the links here as I can also add addtional notes to theses links/sites and organise them in a table. However, I do not save links that all of the team need regulary. I won’t let this page become a project space starting page. That should be in the project documentation.

Backend Stuff

I work as a hard- and firmware developper, so the backend is not my focus area. However, I also find myself look up things in the backend and occasionally need some more specific infos that I store here. Additionally, I can complement the documentation with notes that backend developpers do not need, but help me to understand their area.

Git Stuff / Linux Stuff

As we use git and work on linux I regularly need to look up the commands that I do not need on a daily basis. However, I often need the same or similar commands.

For example I have the command

git fetch -p origin

just to remind me, that from time to time I can clean up my local branches.

Or more complex commands, for example the following to print local branches that are not on the remote

git branch --format "%(refname:short) %(upstream)" | awk '{if (!$2) print $1;}'

that I once found here.

The benefit of having them saved on the Confluence personal space is that I am able to adapt the commands to the personal needs. For example in our repository our squad works on the feature branch squad-xx. I therefore adapted the command to delete local branches that are merged on the remote to automatically inlcude this squad-xx branch but also work on our other repositories with a different main/master branch.

git branch --merged | egrep -v "(^\*|master|main|squad-xx)" | xargs git branch -d

In the field of general linux commands for example, I saved the command to create a virtual python environment with a different python version than the default one. And I also have several prepared grep commands to speed up my search process.

Project Stuff / Testsetup Stuff

The Project Stuff and Testsetup Stuff pages contain commands that I personalised with my directory layout and the Universally Unique Identifiers (UUID) of my devices. This is the page I probably use the most as I just cannot remember the UUIDs.

Temporary Documentation Pages

If I do not know yet where to put a new page or if I am hunting bugs and do not know if it will be benefitial to post the process and findings in the project documentation, I create a new temporary page here. The big advantage is that the page is already correctly formatted if it turns out to be important for the project. Additionally, I can start documenting the bug hunting like a diary and I can easily consult help from my team colleages and share my progress. But thesese pages may only reside temporarily in my Confluence personal space. If they are important for the project, I move them into the project space. Otherwise I delete them afterwards.

Setup, Share and Move the Personal Space

Setup

The setup of the Confluence personal space is straigth forward:

• Choose your profile picture at the right side of the Confluence header
• Select Add Personal Space…
• Hit Create

Now you already have your personal space.

Share

To give access, you can simply:

• Choose Space tools > Permissions from the bottom of the siderbar
• Hit Edit Permissions (enter your password if prompted)
  You should see the confluence-users group listed under Groups. To the left of the list of permissions is the View permission, which determines whether everyone in that group can see your space.
• You can also add individual people

If you want to restrict a specific page, you can do this directly on the page using the lock symbol at the top, next to the navigation bar. However, I do not use restricted pages.

Move

A page can easily be moved, even accross spaces:

• Open desired page
• Select the 3 dots menu at the top right -> Move
• Select the new paren space and page

Conclusion about Personal Notes in Confluence

As you probably could see, I put several notes in the Confluence personal space as an addition to the project space. I think it is important, that the personal space never contains information that other team collegues need regularly. If so, you should most probably move this information into the project space. In contrast, I also do not think that the information like commands prepared for my UUIDs belongs into the project space documentation.

What is your work flow? Where do you store your notes? How do you handle such informations and code snippeds?

Do you prefer *.txt documents, OneNote or Word / LibreOffice documents?

Feel free to comment and share your experience.

Im Elektrotechnik Studium erstellten wir viele Grafiken und Berechnungen mit MATLAB. Während dem Studium habe ich mir eine Studentenlizenz gekauft, um den «Luxus» von MATLAB jederzeit zu nutzen. Sobald ich jedoch etwas für einen Kunden evaluieren will, darf ich diese Lizenz nicht mehr benutzen. Steht keine MATLAB-Lizenz zur Verfügung, bedeutet das, dass man eine Alternative braucht.

Alternativen zu MATLAB

Octave

Natürlich kenne ich die freie alternative Octave. Octave ist zu einem Grossteil kompatibel zu MATLAB und der Einstieg daher einfach. Erfahrungen mit Octave habe ich bisher wenig gemacht. Ich hatte einmal eine Simulation aus Neugierde in Octave implementiert und festgestellt, dass die Berechnung wesentlich länger dauerte als mit MATLAB. Diese Erkenntnis aufgrund meines Tests zu generalisieren, wage ich mich jedoch nicht.

Python

Python war in meinem Studiumalltag nicht präsent. Eingesetzt hatte ich es nur 2-3 mal um .csv Files nach vorgegebenen Mustern zu editieren und schätzte die umfangreichen Möglichkeiten einen Task zu lösen.

Der Entscheid für einen Ersatz

Idealerweise kennt man alle drei Tools sehr gut und kann sich vor Beginn für die effizienteste und die kostengünstigste Variante entscheiden. Da MATLAB wegen der hohen Lizenzkosten nicht als erstes in Frage kommt, bleiben noch Octave und Python. Da ich von Python nur sehr wenig kenne, versuche ich den Einstieg hier zusammenzufassen und die ersten Erkenntnisse zu ziehen. So kann ich mich später fundierter für eine Variante entscheiden.

Installation von Python unter Windows 10

Die Installation kann man ziemlich klein halten, wenn man Python direkt installiert und die zusätzlich benötigten Pakete mit “pip” hinzufügt. Der Versuch die Spyder IDE mit “pip” auf meinen beiden Rechnern zu installieren scheiterte auf einem. Den Unterschied in der Installation konnte ich nicht ausfindig machen. Auf der offiziellen Spyder Homepage wird auf die Anaconda Distribution als empfohlene Installationsvariante verwiesen. Anaconda installiert die für den Anfang benötigten Pakete, sowie die Spyder IDE. Es ist also empfehlenswert mit Anaconda (Version Python 3.7) zu beginnen.

Die ersten Plots mit Python

Spyder lässt sich nun entweder via den Anaconda Navigator oder direkt unter Windows→Spyder starten. Unter Ansicht→Fensterlayouts→Matlab Layout kann das Layout so angepasst werden, dass es für MATLAB Nutzer vertrauter aussieht. Plots werden standardmässig im Konsolenfenster angezeigt, da Spyder im Hintergrund IPython nutzt. Will man die Plots wie in MATLAB in einem neuen Fenster, kann man unter Werkzeuge→Voreinstellungen→IPython-Konsole im Tab Grafik das Grafik-Backend von Inline auf Automatisch stellen. Damit die Änderung übernommen wird, muss der Kernel neu gestartet werden: Konsolen→Kernel neu starten.

Ansicht der Spyder IDE im MATLAB Fensterlayout

Beispiel Gauss Simple

Das nachfolgende Skript generiert eine Gausskurve im Bereich [-4, 4] und zeigt so bereits einige Unterschiede zu MATLAB. Als erstes fällt auf, dass in Python, je nach verwendeten Funktionen, die entsprechenden Pakete importiert werden müssen. Für dieses Beispiel sind es die Funktionen figure, plot und weitere aus matplotlib.pyplot sowie die Funktionen  linspace, sqrt und exp aus numpy. Um die Schreibarbeit klein zu halten und trotzdem mögliche Namenskonflikte mit verschiedenen Paketen zu vermeiden, importieren wir hier die Funktion, respektive die Funktionssammlung aus dem Submodule pyplot, von matplotlib.pyplot als plt und alles aus numpy als np. Diese Kürzel sind praktisch Standards, da sie bereits in den Beispielen der Pakete so verwendet werden.

# Import required packages
import matplotlib.pyplot as plt
import numpy as np

# Gaussian curve constants
mu = 0
sig = 1

# X- and y-axes to be plotted
x = np.linspace(-4,4,81) # X-axis: Create 81 Points in the range [-4, 4]
# Y-axis: Evaluate desired function over the x-range
fx = 1/(np.sqrt(2*np.pi*sig**2)) * np.exp(-1/2 * ((x-mu)/sig)**2)

fig = plt.figure(1) # Set up new figure 1 and save the figure handle
plt.clf() # Clear the current figure

plt.plot(x,fx, label='Normal distribution') # or ax.plot(x,fx) to plot on specific axis

plt.legend() # Display legend
plt.xlabel('Deviation') # Label current x-axis
plt.ylabel('Probability') # Label current y-axis
plt.title('Plot Demo') # Set current axis title

# Show plot
plt.show()

Figure Fenster des Beispiels Gauss Simple

Beispiel Gauss Extended

Im 2. Beispiel werden einige Kurven mehr gezeichnet, Subplots verwendet und Achsen im LaTeX Format angeschrieben.

# Import required packages
import matplotlib.pyplot as plt
import numpy as np

# Define a function
def gauss(mu, sig, x):
    # Probability density function of the normal distribution  
    # mu equals the mean
    # sig equals the standard deviation
    # x equals the point being evaluated
    return ( 1 / (np.sqrt(2*np.pi*sig**2)) * np.exp(-1/2 * ((x-mu)/sig)**2))

# Gaussian curve parameters to be evaluated
# mu    = 0.0,  2.5,  2.0,  -0.7
# sig   = 1.0,  3.0,  0.5,   0.8
simParamPairs = [[0,1], [2.5,3], [2,0.5],[-0.7,0.8]]

xmin = -4       # Minimum of x-axis
xmax = 4        # Maximum of x-axis
nrPoints = 81   # Number of points to be evaluated along x-axis

x = np.linspace(xmin,xmax,nrPoints) # Create x-axis array
dxArea = (xmax-xmin)/(nrPoints-1)   # Calculate space between x-points

# Create new figure 1, clear if it already exists and save figure handle
fig = plt.figure(num=2, clear=True) 
plt.suptitle('Normal Distribution for Plot Demonstration', fontsize=16) # Set main title

# Create 2 Subplots in 2 rows and 1 column and save axis handles
ax1 = plt.subplot(2,1,1) # 2 rows, 1 column, figure 1
ax2 = plt.subplot(2,1,2, sharex=ax1) # 2 rows, 1 column, figure 2, Link x-axis

labels = [] # Create empty label array

# Iterate over all parameter pairs
for simParamPair in simParamPairs:
    fx = gauss(simParamPair[0],simParamPair[1],x) # Evaluate each parameter pair
    ax1.plot(x,fx) # Plot fx along x
    # Plot the cumulative sum of fx. To respect the area multiply by the distance
    # between two points. Note that this is not accurate, just for demonstration
    ax2.plot(x,np.cumsum(fx)*dxArea)
    # Generate and append the label for the current graph, formatted like LaTeX
    labels.append(r'$\mu = %.1f, \sigma = %.1f$' % (simParamPair[0], simParamPair[1]))

ax1.grid(b=True, which='major', axis='both') # Enable both major grids
ax1.set_xlim(xmin,xmax) # Set x limits
ax1.set_ylabel(r'$\varphi_{\mu,\sigma^2}(X)$') # Set y label, formatted like LaTeX
ax1.set_xlabel(r'$X$') # Set x label, formatted like LaTeX
ax1.set_title('Probability density function') # Set subplot title
ax1.legend(labels, loc='upper left', fontsize=9) # Add legend

ax2.grid(b=True, which='major', axis='both') # Enable both major grids
ax2.set_xlim(xmin,xmax) # Set x limits
ax2.set_ylabel(r'$\Phi_{\mu,\sigma^2}(X)$') # Set y label, formatted like LaTeX
ax2.set_xlabel(r'$X$') # Set x label, formatted like LaTeX
ax2.set_title('Cumulative distribution function') # Set subplot title
ax2.legend(labels, loc='upper left', fontsize=9) # Add legend

# Adjust the spacings between and around the subplot area
plt.subplots_adjust(top=0.88, bottom=0.1, left=0.12, right=0.95, hspace=0.5,
                    wspace=0.5)

# Save plot as png. Possible are: png, eps, pdf, pgf, ps, raw and svg
fig.savefig("gaussExtended.png")
 
plt.show() # Show plot

Gespeichertes Bild des Beispiels Gauss Extended

Meine Erkenntnisse zu Python statt MATLAB

• Die Installation kann bereits die erste Herausforderung sein. Nutzt man Anaconda wird einem vieles abgenommen und das Einrichten ist unkompliziert.
• Es gibt sehr viele unterschiedliche Arten wie man z.B. das 2. Beispiel aufbauen kann; Mit verschiedenen Array-Arten und entsprechenden for-Loops oder wie man mit den Axis-Handles jonglieren kann.
• Viele Funktionen sind in zusätzlichen Paketen implementiert und müssen daher importiert werden. Funktionen, die importiert werden, müssen dann über die entsprechenden Namespaces respektive den zugewiesenen lokalen Namespace-Namen, bspw. plt und np, aufgerufen werden.
• Die Dokumentation von MATLAB vermisse ich, da MATLAB für meinen Geschmack eine ausgezeichnete Dokumentation besitzt und ich sie häufig auch direkt aus der Konsole offline benutze.
• Die Dokumentation der Funktionen aus den Paketen numpy und matplotlib.pyplot findet man natürlich online und können auch heruntergeladen werden.
• Alles in allem finde ich Python sehr angenehm, um Berechnungen darzustellen und werde mich die nächsten Male nochmals damit auseinandersetzen.