DEV Community: Jacqui Read

The Knowledge Vault: ADRs

Jacqui Read — Mon, 04 Nov 2024 18:07:00 +0000

I recently added the knowledge vault to JacquiRead.com with a new article: ADRs (Architecture Decision Records).

Why isn’t this in the blog? The knowledge vault is designed to collect information together in detailed reference articles, whereas the blog posts are shorter or more transitory (but still useful of course!).

What do you think of the ADRs article? What topics would you like me to cover in the knowledge vault? Comment below or let me know on social media.

Visit the Knowledge Vault and the ADRs article

Decision Archeology: Using ADRs with Existing Products

Jacqui Read — Sun, 25 Feb 2024 21:38:00 +0000

I've had the same question from a few people lately. They've seen how Architecture Decision Records (ADRs), and other Business Decision Records, improve their software architecture and development process, but they wonder what to do about the decisions made before they started using ADRs. Should you create ADRs for historical decisions?

The answer is most definitely yes. The benefits outweigh the effort. Get stuck in with the following advice:

The benefits of recording historical ADRs

You may find that some historical decisions now need to be reviewed to get the best solution to the problem you are solving.

The benefits are overall the same as for creating any ADR, but with a few additions:

You are filling in the gaps in your architecture decision knowledge and therefore will see the benefits of having ADRs more often (such as being able to point to an ADR to answer a question).
You get the benefit of reviewing that decision with all the new information that you have today. You may find that some historical decisions now need to be reviewed to get the best solution to the problem you are solving.
Where you have done the work of investigating a historical decision you now get to record all your hard work for future-you and others to benefit from. Your effort was not for nothing, and next time your work will show up in search results and you won't have to repeat the investigation.

For those new to the benefits of ADRs here are the main ones:

You avoid accidentally changing decisions that were made for a very good reason, and wasting time and money on investigation and implementation of a new decision that will negatively impact your solution.
They are quick answers to questions that keep popping up or when onboarding a new team member. Current team members do not have to spend time explaining (if they know the reason the decision was made at all) and time isn't wasted looking into the decision.
You don't need to worry about people leaving the company and taking key decision information with them. It is all recorded (and, of course, you have a backup strategy, don't you?).
ADRs can be used to facilitate the decision-making process, enabling multiple people to contribute to the decision asynchronously (or synchronously if you'd prefer).

Use existing information

Even if the documentation for your product is not comprehensive you very likely have some information that you can piece together to generate your historical ADR. When looking at documentation remember that it may have been updated since a decision was originally made. You can also look at repository commit messages which may indicate process and help you find the decision's history.

Good places to look for decision criteria (what the options were possibly scored against) are requirements documents, constraints, and architecture characteristics / non-functional requirements (NFRs). If you were creating an ADR for a new decision these are the sorts of things that you would rate options against. User stories, spikes and meeting minutes may hold other clues. Remember that the criteria you identify may not have been used in the original decision. If you ever decide the historical decision needs review the decision factors you have discovered can act as a basis for your new decision (with any new information added).

It is not compulsory to record options, but if you can accurately see what they were it is worthwhile¹. When attempting to work out what the options considered might have been you may need to do some detective work, especially if more than a couple of years have gone by since the original decision. For example, if the decision involved styles of architecture or how services should be communicating, the options available at the time might be very different to the options available now². Serverless may not have existed. Event-driven distributed architectures may not have been on anyone's radar. Don't accidentally add impossible options to your historical ADR. Stick to facts.

Discover together

You will find that information is spread across a team working on a product, so get input from as many people as you can

If you have already done some digging to discover why a historical decision was made you already have the basis for creating an ADR for that decision. If you haven't yet done that work (or don't feel it is comprehensive), you don't need to complete it all in one go. Think agilely and iterate over the decision record as you find more information.

It is likely that you are not working alone. You may not have even been working on a product when a historical decision was made. Creating a historical ADR should be a collaborative effort. You will find that information is spread across a team working on a product, so get input from as many people as you can (even if it is only sign-off on your assumptions).

Declare assumptions

Speaking of assumptions, it is unlikely you are going to be able to find all the information that you would like to include in your historical ADR. As with any documentation, you must include any assumptions that you have made (maybe you have assumed that on-prem solutions were discounted due to a company policy, or that a particular architecture characteristic was important in making the decision).

Assumptions should be put in front of others in your team to get their input. They may be able to confirm or reject your assumptions, or add more information.

Highlight what isn't there

It is important that anyone reading your ADR in the future is aware of what information isn't included as well as what information is confirmed or assumed.

As well as having to make assumptions about a historical decision you will also find that some information is completely missing. As mentioned above, you won't know all the options that were considered when an option was chosen. You could try to make assumptions, but sometimes there is so little information that making an assumption would just be a stab in the dark (very likely inaccurate).

In this case, you must highlight missing information. Anyone reading your ADR in the future must be aware of what information isn't included as well as what information is confirmed or assumed. Stating that the recording of the decision is being done in hindsight is another good way to show the reader to be wary of the information contained within.

Takeaways

The more comprehensive your ADRs the more you will see the benefits.

Even if you don't know all the facts, having some record of past decisions made is more useful than not. Even something that could seem obvious now may not be in 12 months.

Any time your research turns up a past architecture decision make an ADR to record your findings.
If nothing else create an ADR with the decision made and a note to say you don't have any more information. You at least then have something to refer to and iterate over.
Get input from others to add information to your historical ADR.
Use existing documentation and artefacts to find missing information for your historical ADR (version control messages can also be useful).
Highlight assumptions and missing information for future readers.
It can be a good idea to record decisions that have now been superseded and link to them from the ADR that supersedes them. You then have your history and reasoning preserved for future reference in case that decision is revisited again (even reversed!).

When you are recording a historical decision:

use the same template that you use for new ADRs (if you need one I have a free template on the Communication Patterns website)
set the status as decided or superseded, which you may want to qualify or add a note to indicate it was decided before being recorded (e.g. decided - historically)
add the date the decision was made, which can be an estimated date if needed (e.g. estimated: Q2 2020)
when recording the implications of the decision made you can add any implications that you now know about in hindsight (but label it as such)

Make life easier for future-you and your colleagues by filling in gaps in your historical documentation. The more comprehensive your ADRs the more you will see the benefits.

For more on ADRs check out Chapter 12 from the book Communication Patterns.

For everyone ready to learn more about software architecture or engage our architecture consulting services please get in touch.

©️ Read the Architecture Ltd.

This is not a decision-facilitating ADR (the decision is already made), so the options aren't for comparing potential choices but for understanding the trade-offs that were made. Sometimes an option is chosen due to flaws in an alternative, rather than a feature in the option itself. ↩
Identifying options that didn't exist or were cutting-edge at the time of the historical decision can be very useful in deciding if that decision needs to be reviewed with the new information and options available today. ↩

SDD Conference Top Takeaways - Evolutionary Architecture

Jacqui Read — Mon, 16 May 2022 22:21:49 +0000

These are just a few of my takeaways from Neal Ford's Building Evolutionary Architectures workshop at SDD Conference 2022. More to come.

Bit Rot

Software degrades over time, like cracks appearing in a building. Structural defects can start small and get more problematic. This seems inevitable, but it isn't.
QA helps to reduce degradation, but it doesn't cover everything. It misses the architectural characteristics, e.g. auditability, scalability, performance, etc.

Architectural Characteristics

A full list is not possible, they change over time. You need to create a list specific to your organisation and iterate on it.
Ensure you use ubiquitous language within a project team and across the architects in an organisation.

CHANGE

Tech change is pretty much forced upon us.
If you don't evolve or pivot you get left behind.
Patterns emerge and are given a name when they are recognised as a good solution to a problem.

Q: How is long-term planning possible?
A: Plan for things to change!

Evolutionary Architecture

"An evolutionary architecture supports guided, incremental change across multiple dimensions." i.e. architectural characteristics that are relevant to the project.

Fitness Functions

Automating checks for architectural characteristic support work in the same way as unit tests.
Higher level functions will require possibly stringing things together, as there isn't a specific library or tool that can be used.
You are creating an objective integrity assessment of one or more architectural characteristics.
Iterate. You don't know what you don't know. Things will change.

All architectures become iterative because of unknown unknowns; agile just recognizes this and does it sooner. - Mark Richards

Fitness functions overlap with other premises, e.g. monitors, unit tests, chaos engineering…

Some Examples of Architectural Fitness Functions

Cyclic Dependency Function - ensure you don't have e.g. ClassA referencing ClassB that references ClassC, which references Class A… This is a small thing that can be missed and leads to Bit Rot.
Directionality of imports - ensure rules on this are followed.
Data displayed on screen is not stale - ensure HIPPA is followed for US healthcare systems.
Chaos Monkey & the Simian Army - check your system copes with systems, availability zones and even whole cloud regions being taken down.
Naming conventions - ensure that naming conventions are followed by specifying a pattern to use or antipattern to avoid.
Afferent (incoming) and efferent (outgoing) coupling - check whether coupling falls within specified limits.
Identify changes in open-source software licenses - make sure any changes in open-source software you depend on are put under the noses of your legal team.

Developer Torture is not the aim

Architects and developers need to work together.
Fitness functions are a checklist to stop important things falling through the cracks. Doctors use checklists too!

What makes microservices so evolvable?

Extremely lose coupling.
Fine granularity / small quanta, including any data stores.

Implementing Fitness Functions

Identify your dimensions (including architectural characteristics and linked metrics)
Define fitness functions for them.
Use deployment pipelines to run your fitness functions (quick and atomic functions running earlier than slow and holistic functions)

Low/No Code

Beware of the Last 10% antipattern! 80% of requirements are implemented easily, the next 10% are hard as the tool/platform doesn't really support them, the last 10% are impossible. Low/No Code is prone to this, otherwise we would all be using it!
Try the hardest thing as a proof-of-concept (PoC), not the simplest (we would hope it can do that easily!). Will it really do what you need?
If it acts like code it should be handled like code with unit tests, versioning, etc.

If it looks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck.

We're told low/no code isn't for developers so it doesn't integrate with pipelines, version control, etc.

Some Tools for fitness functions

ArchUnit
NetArchTest
BlackDuck
Dependabot
Scientist
Jupyter notebooks: document and have fitness functions together. Executes on opening.
Cucumber
Architecture Decision Records (ADRs)

Resources

Building Evolutionary Architectures by Neal Ford, Rebecca Parsons & Patrick Kua
Refactoring Databases by Scott W. Ambler & Pramod J. Sadalage

What next?

Let me know if there is anything specific you would like me to expand on. More to come from SDD 2022.

The Data Motivator

Jacqui Read — Wed, 13 May 2020 08:53:06 +0000

You're now at home and sat in front of a different desk or screen all day, but you're still in front of a screen for a lot of hours. You know you should be more active for your health, especially in our current situation, but what is going to really motivate you to get active?

Me, active?

I don't mean going out and running a half marathon or cycling 50k, just activating yourself, raising your heart rate and getting going each day, or at least 3-4 times per week.

What's your motivator?

As a techie what do you like? Personally I quite like data. I could go for a walk each day but I want to know about that walk: how long was it, how far did I go, was I faster than yesterday? It's also nice to know what my face-to-face or online friends are up to as well. Am I quicker or more active?

Get That Data

So: data. Collecting this data is very simply in reach via your smartphone. Download an app like Strava [Android | Apple], Google Fit, iOS Health or any of the many other apps that you might like, available on the Android and Apple app stores.

There are loads of free ones. I personally use Strava, which I was recommended by a friend, which is great as we both 'follow' each other and can see what we are both up to. There is also the option to require all your followers to be approved by you, which I highly recommend.

Simply install, set up an account, put your shoes on, and off you go. Some apps will track automatically and others you will need to tell to start recording (e.g. Strava).

Compare and Contrast

Once you've done this twice or more you can compare your data. When you've connected to friends via the app (many like Strava can synchronise with your contacts to automatically find your friends).

If you have a watch (e.g. Fitbit or similar) or another monitor like a Garmin chest band then you can collect and compare even more data. What was your average heart rate? Were you in cardio or fat burning and for how long?

Motivation Challenge

You will likely find that the data and friendly competition between friends is a great motivator to get active and challenge yourself. A challenge to one person may be a 1k walk or 10 pushups, to another, it may be a 10k run or a 30-mile bike ride.

Set yourself a goal and some quickly achievable milestones on the way to that goal. These milestones will be more motivation for you as you work your way towards your goal.

Keep going, keep pushing, and get active to improve your health in these unprecedented times. But above all please make sure you are observing social distancing and all the current rules wherever you are in the world.

Stay Home. Stay Safe. Protect Front Line & Key Workers. Keep Active.

Tips for your Code Journal | Code Journaling pt 4 of 4

Jacqui Read — Mon, 30 Sep 2019 22:17:32 +0000

In this final post of my series on Code Journalling, I am giving you some further tips on creating and using your Code Journal to its full potential. If you have any more tips please include them in the comments at the bottom.

Don't be precious or a perfectionist, get agile!

If you try to make it perfect you will never get anything written down, or at least not as much as you could. A bit of planning is a good idea, but don't put off starting!

Getting something down on paper, then refining it, is agile practice in your own work. A Code Journal will not work well using the Waterfall method, so make your own journaling practise agile.

Use the index

Always write the page number and content into your index, so your amazing ideas are never lost.

Your index will be your main reference to find something specific or to get an idea of what you have recorded in your Code Journal. Make sure that all pages are numbered and written in the index for future reference.

Set up regular reviews

Schedule reviews into your calendar or diary, e.g. weekly, monthly, quarterly, yearly, and stick to them. It is up to you what you review, make it work for you and change it if you need to.

Ideas for your Review

These are just a few ideas for what you could review. Tailor it to your own needs.

Your Goals, and your progress towards them

Are you on target?
What have you done to work towards your goal?
What is the next step to work towards this goal?
When are you going to do it by?

Projects

How are they progressing?
Which one should you be working on now?
Is there another project you want to start?

Records of praise, successes, failures, etc

Are these up to date?
Have you analysed why something went right or wrong?

Training and Skills

What have you done since your last review?
Are you on target?
What is your next step?

Start Doing | Keep Doing | Stop Doing

Use this template to do an analysis for the whole review period and record everything under these headings.
Review your last recorded Start Doing | Keep Doing | Stop Doing record.

Create a ritual

Journal regularly, at least a few times per week. Preferably write something each day, even if just a few words. Making journaling a regular thing will make you much less likely to forget.

Slipping out of the habit of journaling will set you back in your goals and waste your time when you are trying to remember things. Try to plan your journaling into your schedule, but also do it on an ad hoc basis when needed to get stuff out of your head.

Don't leave space

That's why you have an index. It doesn't matter if you end up with notes on a project in three different parts of your journal, it is all in the index.

This can be a hard habit to crack, especially for any perfectionists among us (myself included!), but the index is your friend and you won't end up with unused pages in random places, or not having enough space in what you left anyway!

KISS!

Keep It Simple Stupid. You don't want to create an unwieldy monster, so stick to the simplest solutions. Don't create something that you don't want to keep up to date. This shouldn't stop you from experimenting though!

Look for inspiration

But don't compare. Some people publish photos of their beautiful copper-plate handwriting and colourful art in their journals. This is not what your Code Journal should be (unless that is really you).

You want the ideas, but you are not some Instagram Influencer that needs to keep up with those who are. Your journal is for your own eyes only and needs to work for you and you alone.

Experiment

Then stick with it to give what you are doing a chance. Analyse, make small changes or pivot completely. Don't be afraid to try new things or reinstate something you tried before that worked better.

This is another idea along the lines of making your own journaling methods agile.

Make it yours

The content of your Code Journal will be unique to you, but so will the aesthetics. Where one developer likes black and white, another will have a rainbow of colours on every page.

It's completely up to you if you want to jazz things up a little. Colour may help you to find the information you want, or inspire you, or it may be a distraction.

Make your Code Journal work for you.

GTD & The One Thing

Ideas from Getting Things Done and The One Thing may be useful to you. These are two different systems for personal organisation and productivity. I recommend reading up on both of these. There are plenty of free resources, or the two books are not expensive.

Bullet Journalling

If you want to take your journal further and use it as an organiser as well (or maybe you want a separate organiser) then you need to look into Bullet Journalling.

Learn the basics at bulletjournal.com and then look through the myriad of blogs, Instagram posts, Pinterest boards and Youtube videos for more inspiration, how-tos and tips.

Here are a few blogs to get you started:

What next?

Enjoy your new Code Journal and remember it is a tool that you can modify and experiment with to meet your own needs.

If you have started a Code Journal, or have anything to add that isn't in this series, please leave a comment below or contact me directly, I am always interested in feedback.

Originally published at http://www.jacqui.tk/blog on September 30, 2019.

What to write in your Code Journal | Code Journaling pt 3 of 4

Jacqui Read — Thu, 26 Sep 2019 14:30:13 +0000

In this third part of my series on Code Journaling I am covering some ideas for what to actually record in your Code Journal. These are only ideas, and you should pick and choose what works for you.

Do you have any other ideas for what to write in a Code Journal? Please put them in the comments below.

What to write

If you don’t know what to write then just write. Writing a few sentences each day, to collect your thoughts or record what you have done is a great place to start. That said, here are a few ideas for spreads (one or more pages) that you may want to include.

Start writing, no matter what. The water does not flow until the faucet is turned on.

Louis L’Amour

Index and/or Section Index

This is the first thing you should create in a notebook. To create an index in your notebook simply put aside 2-4 pages at the beginning of your Code Journal and title them Index. Some notebooks have page numbers, if they don’t you just need to number a page when you use it and write its content in the index.

A Section Index is a useful tool to break down your notes more fully and is a grouping for a type of notes (I will discuss some section ideas later on). The basic idea is that you add the Section Index to your Index (e.g. p.8 Project Index). Then on your Section Index page, you create an index for that type of note (e.g. p.9 Project Parlour, p.23 Minki Inc., etc). This grouping means you do not need to search through the whole main index, trying to spot what you need, you simply find the appropriate Section Index and find it in this smaller index.

For a digital Code Journal, an index will take different forms depending on how you have set it up and what platform you are using. With Evernote, you will likely use different digital notebooks and labels, possibly with a note that acts as an index. If you are using online documents, like Google Docs/Drive, then you probably will want a document as an index, and use folders to organise your documents. The search functions in digital journals will be a help, but it is good to see what you have notes on at a glance.

Regular/Daily Notes

Even if you don’t make notes every day, it is good to get into a ritual of writing something when you are coding. It may just be a note about what you need to do next, but notes about why you have made a decision, or observations about yours or others coding are going to be useful when you review them in the future. Making a note of what you need to do next will save you a lot of time when you next come back to that project.

Goal Tracking

Many people set goals for the year/quarter/month, but when they get to the end of that timescale how do they know if they have met their goal? Did they even remember to work towards it?

Keeping your goals, breaking them down into steps, and recording notes on your progress towards them in your Code Journal will mean you can set up a ritual of reviewing your goals and progress, making you much more likely to reach your goals in the intended timescale.

Is your goal to learn a new programming language in the next year? Write it down, along with the steps you need to take (or at least the next step you need to take), and record everything you do towards your goal. When you watch a course video, go to a meet-up or write some code, make a note of your progress.

Make a habit of reviewing your goals on a regular basis, at least monthly (or more regularly for shorter-term goals). This will keep them fresh in your mind and keep you moving on to the next step for each goal.

Training & Skills

Alongside formal training, you are likely learning a lot informally. Keeping track of your current skills and learning will be a great help when setting future goals, updating your CV or asking for a pay rise or promotion.

You could have a page where you record any learning on a particular subject, or a page where you record all learning on everything, or you could have a page for recording courses, one for video courses, etc. The Code Journal should work for you, so you may want to experiment.

Project Tracking

It is a good idea to keep track of your projects, whether they are ones you are working on in your day job or personal ones.

This is part of your experience and will be as helpful as recording your training and skills when it comes to preparing for interviews, updating your CV or going for a promotion or pay rise. It can also help you to work out what you enjoy and what you don’t enjoy, to help you plan for your future in coding.

Technologies

Notes on technologies you use are another thing that will be very useful for future planning, your CV, pay rise, etc. This is also a really useful record when you are looking for the solution to a problem, or you are in an architect role.

Having a record of technologies you have used, and how, and also technologies you have researched is a valuable resource. Next time you are looking for a solution you can see quickly any technologies you have written off in the past, and the reasons why. You also have information on the pros and cons of a particular technology, so you can quickly work out if it will solve your new problem.

Keeping a record of useful resources for technologies, or how you solved a problem with a particular language, will be a useful resource to you when you want to work with that technology again.

Successes, Failures & Praise

When you experience success or receive praise for something you should record it, not just for use for things like asking for a pay rise, but also to remind yourself of positive things when times aren’t so rosy. Reviewing past successes and praise will help you to get past bouts of Imposter Syndrome if that is something you suffer from. Verbal praise is particularly important to record, as you have no other record of it.

It is also important to record your failures, not to put yourself down but so that you can learn from the past in order to not repeat these failures in the future. Why did something go wrong? What would you have done in hindsight? Could it have been foreseen? How will you avoid this issue in the future? How was it fixed? Could it have been fixed in a better way?

Decisions

Yous, your team’s and others’ decisions are a good thing to record in the context of your projects, technology research, goals and future planning. They will save you time in the future where you won’t need to make the same decision again because you will have a record of why you made the decision one way or the other.

This record can also come in useful if you need to report to someone about the progress of a project or why something has gone well or badly. If you have a record of why the project went in a particular direction then this process will be so much easier.

Start Doing | Keep Doing | Stop Doing

This is a good review to do regularly; monthly, quarterly, annually, maybe even weekly when working on something new. It gives you the opportunity to analyse what is working for you (keep doing), what isn’t working for you (stop doing) and how you can improve (start doing).

This process is a good way to implement agile in your own work and processes. You are constantly experimenting and pivoting to improve yourself a little each day or week or month.

Every action you take is a vote for the type of person you wish to become. No single instance will transform your beliefs, but as the votes build up, so does the evidence of your new identity.

James Clear

Future & career planning

Similar to goals, but with a longer time scale. Your aims for your future and career may change over the course of years or they may not. Keeping a record of your thoughts and ideas about your future will enable you to set short- and medium-term goals that will lead you towards your target.

As you gain more experience you can update these plans and maybe even pivot towards something completely different. Using your Code Journal in this way will help you to plan and keep your plans in mind, in order to keep you on the path towards them. Thinking about your future on a regular basis will mean you can avoid going too far down a road that you don’t want to travel.

What next?

In my next post in this series, I will cover some tips on how to use your Code Journal to its full potential.

Originally published at http://www.jacqui.tk/blog on September 23, 2019.

How to start your Code Journal | Code Journaling pt 2 of 4

Jacqui Read — Thu, 26 Sep 2019 14:27:45 +0000

In this second post in my series on Code Journaling, I will cover how to start your own Code Journal.

Choose your medium

The medium of your Code journal is an important decision. Just as the content will be individual to you so will your preference for analogue or digital, and the exact choice of a medium within those categories.

Some people may already use a notebook (analogue) and some may be full converts to using Evernote (digital) for everything they do. Here are a few pros and cons of each category and some non-exhaustive options for each:

Analog is more beautiful than digital, really, but we go for comfort.

Anton Corbijn

Analogue

This category covers everything that does not require something like a phone, tablet or computer to access (i.e. no electricity).

Pros

You slow down and think about what you are writing.
You can’t be hacked or lose data.
Writing stimulates and engages your brain better, and has been shown to produce more content, expressing more ideas, and faster than typing. 1
It gets you away from your screen!

Cons

If you lose it there is no backup (unless you make a copy).
It’s only accessible wherever the physical copy is.

Analogue Options

B5 dotted notebook

I find this a good size for a Code Journal, not too small, but enough space and not bulky. Dotted paper is the most flexible as you can use it to easily write lines of text, create tables or draw diagrams. I personally use this ZenArt notebook, but their newer version is linked to above.

A5 dotted notebook

Smaller for those who want to save weight or space, or maybe your small handwriting gets lost in a larger notebook. Again, I recommend dotted, but it is up to you. I have personally used a Scribbles that Matter dotted notebook for other projects.

A4 dotted notebook

For those who want more space on a page. Moleskine produces an extra-large dotted notebook, which I have heard good things about.

A notebook with removable pages or a folder and paper pad

If you like to move your content around to organise it then these options are for you (although I will tell you all about using an index, which negates the need for moving things around, later on).

Digital

There are lots of digital options, some on specific physical devices and some in the cloud, accessible wherever you are. You are probably already using several digital notebooks.

Pros

Can be accessible from more than one place.
Easy to back up.
Quick to search.
Can make it easier to stick with the habit of keeping a journal, of any kind.

Cons

If your account is hacked you could have data stolen or lose it altogether.
There are a lot of distractions when using a digital device (email, Facebook, etc).

Digital Options

Evernote

Great for organising your coding journal, and can be used for other things at the same time by having multiple notebooks. Searchable via text and tags and heavily customisable.

WordPress blog

Self-host or use WordPress.com. You are in control of whether a post is public or private. There are lots of plugins for heavy customisation.

Diaro

Available online, on Android, on iOS and on amazon. A very flexible diary app. Other similar apps are available, but this is the one I have used.

A Word, Google Doc, or another similar online document

Create a system that works for you in Office Online, Google Docs, Zoho, or similar, using a folder structure and appropriate types of file.

My Preference

For my Code Journal, I currently use a ZenArt B5 dotted notebook. I find the size to be about right for what I want to do with it, and it is good quality and good value for money. The dotted paper is flexible to writing, tables or drawing. (There is now a new version of this notebook)

I use a Main Index and Section Indexes, so I can find things easily. It gets me away from a screen and allows me to slow down, disconnect and let the writing flow.

What next?

In my next post in this series on Code Journaling, I will look at what to actually write in your Code Journal.

Originally published at http://www.jacqui.tk/blog on September 16, 2019.

Why you should keep a Code Journal | Code Journaling pt 1 of 4

Jacqui Read — Thu, 26 Sep 2019 12:21:52 +0000

Journaling is often thought of as an arty or holistic pastime, an activity for those with a creative streak or too much time on their hands. Why would a technical person be interested in journaling?

Journaling is a tool, and a Code Journal is a tool for anyone who uses technology (not just specifically code), be it in their job or as a hobby (developers, software architects, QA/testers, etc).

The stereotypical type of journaling is usually considered to be a tool for improving mental and spiritual health, the Code Journal is a tool to improve your coding and work/hobby life.

In this post I will visit a few reasons for why you should keep a Code Journal then, in the next post in this series, I will give you some ideas for starting a Code Journal. There are no hard and fast rules, your Code Journal will be tailored to you and what you need from it.

The benefits of keeping a Code Journal

Get everything out of your head

If you want to remember to do something and you want to free up your mind to do what it should be doing (thinking!) then you need to get everything out of your head. Using a Code journal for this means that you won’t lose that vitally important Post-It note with your world-changing idea scribbled on it. Your brain will thank you for letting it think, instead of remembering.

Your mind is for having ideas, not holding them.

David Allen

Track your growth

You can track your growth and see how you have improved. Without a record, it is very hard to see how far you have come. Most of us will feel we are stuck in a rut, or falling behind, at some point. Your Code Journal can either show you that you are actually improving, or it can help you identify what you are missing and to then set goals.

Track your goals and progress

You can track your goals and any progress made against them. Keeping your goals at the forefront of your mind, and keeping track of progress will move you toward your goals much faster. A Code Journal gives you somewhere to record and review your goals, to keep you on track for any deadlines set.

Pick battles big enough to matter, small enough to win.

Jonathan Kozol

Save time

Because of the records, you make in your Code Journal, it will be easier to carry on where you left off. You won’t waste time trying to remember where you got to in your project or what you planned to do next, even if there has been a long space of time since you worked on it.

Manage multiple projects more easily

It will be easier to switch between projects. Most people have more that one project on the go at a time, and looking at your last notes on a project will get you going again much quicker, reminding you what you need to look at next.

Develop a coding or working philosophy

A Code Journal will help you to develop a coding philosophy. Thinking about and analysing how you code and your own (or team/company) processes will mean you can identify what works, what needs improvement and how new ideas can fit into your coding. A more streamlined and simplified process and codebase should be the result.

Document what works and what doesn’t work

You can record things that work well or don’t work well. Having a reference for things to keep doing, things to stop doing and things to start doing will keep you on the path to improvement. Keeping a record and reviewing regularly is the key to improvement.

Keep track of decisions

You can keep track of the decisions you make about your projects, learning, etc. Can you remember why you made a particular decision, or what the decision actually was? If you now have more information, to inform that decision, you can work out if the decision needs to be revisited. You also have a reference so that you don’t have to make the same decisions again, so you’re not wasting your time.

Reduce time to market

Keep track of feature and refactoring ideas to reduce feature creep. This is an easy trap to fall into, especially in personal projects. If you keep adding new features to your current development cycle you will never deploy that app! Keeping a record of new feature and refactoring ideas will mean you won’t be worrying about forgetting your ideas and they can be considered for a future release.

Delivering good software today is often better than perfect software tomorrow.

The Pragmatic Programmer

Identify and eliminate bottlenecks

You will more easily identify bottlenecks or anything that is holding you back. Identifying things that need tweaking or skills that need to be learned will increase the speed at which you grow as a coder. Improving bottlenecks, over other areas, is likely to give you the most return on your effort.

Any improvements made anywhere besides the bottleneck are an illusion.

Gene Kim

Discover your Happy

Why do you like doing what you are doing? What is it that you enjoy? Work this out and you can focus on what makes you feel good about coding to improve your everyday happiness and help you set goals to move you further towards what makes you happy. Reviewing your Code Journal will help you work these things out much faster.

I’ve always thought people would find a lot more pleasure in their routines if they burst into song at significant moments.

John Barrowman

Gather evidence to gain a promotion or pay rise

Most organisations will require a good reason if you want a pay rise and/or a promotion. Your Code Journal is the ideal place to record exactly what you have been working on, and particularly your successes and praise from others. Don’t forget to include things from outside of your job role, such as open-source projects you may be working on. You can also make notes on your research on current market rates for your role, or role you aspire to.

Update your CV and prep for interviews with ease

Your Code Journal will be your best friend when it comes to updating your CV and practising answers for job interviews. You have a record of the technologies you have used, the projects you have worked on, problems you have solved, how you approached a difficult situation… If this list sounds a little like a question prep list for a job interview then you probably get the idea that prepping for these general interview questions by referring to your Code Journal is going to be so much easier than trying to remember everything you have done for the last x months or years.

What next?

In my next post on this series of Code Journaling, I will cover how to get started with your own Code Journal.

Originally published at http://www.jacqui.tk/blog on September 9, 2019.