Work Journaling

Intro

I've used a technique I call Work Journaling since 2005 to capture weekly doc work and notes, for keeping myself honest and my projects on track, and as a handy resource for centralizing information that is relevant to my work.

Personal story

As I started my career as a technical writer (TW), I thought everything would be a breeze: coworkers would ask me for writing assistance and I would wave my (digital) pen and the project would be magically done. At the end of my first month as a TW, my manager asked me for a summary of the work I completed. "Well, I did some stuff on project X and started things on Y." My manager wasn't too happy with that summary. He advised me to take better notes on the work I started and completed in the next month. So I did. I created a folder on my Linux machine, named a text file June-2005.txt, and wrote my first note: "Completed project Y on 6/3/2005. 3 hours." I did this every time I started and completed a project. Happy, I submitted what looked like a grocery list to my manager at the end of the month. He commented that this was an improvement but I was still missing details. So I added more details and the day before the end of the month, I summarized my accomplishments down to 2-3 lines. Still better but if you asked me what I did a few months back, who I worked with, what resources I sourced from, I couldn't even guess. At this point, my weekly text file was just enough to hopefully jog my memory but the real show stopper was when it came to writing up a quarterly summary. I poured through my text files in a desperate attempt to identify what I accomplished, what was impactful, and useful to the people requesting documentation. Every month or so for the first year, I iterated on this person system until it included several levels of detail (what, who, where, when, resources, links, etc.) all categorized by projects or teams. I had found a workflow that suited my needs and style of project tracking.

Journal Levels

I recently learned that my work journal is another form of a bullet journal but only my version was all digital. I developed several patterns for using my work journal and they are basically expressed like this:

• Minimal - sporadically noting your work
• Semi organized - uses some form of structure, includes dates, and more frequent work notes
• High organized - requires a daily habit of including work accomplished, includes who you worked with, why you worked on a project, where your work can be found, links to important resources and project tickets, a section for a weekly summary, and a section for current high and low priority projects

These levels all depend on your end goal with keeping a work journal. Are you trying to keep yourself on track? Write better regular summaries? Remind yourself of what you did before you left for a long vacation? All the above?

Journaling Strategy

A typical TW has several locations to find stats, metrics, project tickets, project-related resources, and multiple platforms where content may be sourced. Utilizing a work journal as a personal information hub and as an extension of project tracking, I have found that work journaling is a much better resource to centralize all your project needs in one platform and system. This habit of keeping a work journal has kept me on track with my projects, their due dates, who I can go to for help, keep me honest, and others accountable.

What should a work journal include? Lets review the five W's:

• What
• Why
• Where
• Who
• When

What

When designing your own template for work journaling, decide on what you need to capture in your notes. How detailed should your notes be? Sometimes a single sentence is enough to capture a week's worth of work for a single project and other times, you may need to write a paragraph to help your future self sort things out when it comes to summary time. You can also keep meeting notes in your journal as well but they shouldn't be included in your weekly summary unless they have some bearing on your project work. Finally, I'm a big fan of linking everything from my work journal. Wiki pages, Jira tickets, work announcements (that affect my work), and other resources that are relevant to my current projects.

Another positive aspect of using a work journal is leaving yourself with information your future self will appreciate as I found most company's internal search and content platform organization can vary greatly and thus be unreliable form of recreating important summaries at critical times.

Why

Another aspect of keeping a work journal is answering the question of "why am I doing X?" Are you handing off a project to someone else? Need extra reminders? Tracking progress on a long-term project? Reaching a milestone summary point? Going on vacation? Why is writing this down important to me and/or the project?

If you're keeping a work journal for the sake of writing, you might be overthinking the process and end up wasting time.

Several years ago, I had a project put on hold. Everyone dropped what they were doing and moved onto different projects. Six or months later, the project was reactivated and I had left myself with enough context in my journal to get myself back on track. In fact, in the first meeting back on this project, the project owner didn’t recall where we had left off and I volunteered a summary of my notes. Within minutes, everyone on the team had a refreshed memory and the project successfully kicked off from there.

Where

Where you keep your journal is important. Keeping it localized to a workstation is good but keeping your notes on a platform that is cloud based so you can access it from any company-enabled workstation is best. Putting your journal in an open wiki isn't a good idea as the content is discoverable by the search engine thus polluting the search results for you and everyone else in the company that has access to this wiki. If your wiki platform has a feature to keep a personal space (like Confluence does), you can use that wiki space as long as the default settings don't expose personal spaces to the search results by default.

Using Google Docs is another option too that I've come to enjoy. Creating a folder for each year with a single document for each week hasn't steered me wrong yet.

Who

Your journal should include who you worked with and who you met with so that you can go back and thank them at the end of a big project or to remind yourself who to ask questions to when you need their assistance.

Consider the audience for your summaries. Does your manager need a regular status update? If so, tailor your summaries for your manager and not the projects. 

Is your journal just for you? If it is, you can simply keep a log of the work you completed, resources, and time spent (minimal approach) as long as it helps you keep on track and keep yourself honest.

Note: Work journals should be devoid of opinions about work or people. Keep the journal focused on the facts of the work. At the end of the day since this journal will likely be kept on a company server, this content is the property of the company. Don’t write something that you’ll later regret.

When

When you update your work journal is completely up to you. Those who adapted to a system like this like to do it throughout a day, at the end of a day, or at the end of a week. I'm more of the "as needed" type. As I wrap up a stage of a project during my work day, I add a little note to myself on what I accomplished, who was involved (if anyone other than myself), and other notes as necessary.

Others keep the meeting notes in a work journal, whenever they start, update, or end a project, or whenever they feel like they captured some important information. Some TWs drop a note or two in their journal and come back at the end of the day to add details so they can pick back up the next work day.

A good way to wind down your work week is to write up your weekly summary. This shouldn't be an exhaustive exercise but rather a quick review of all your project work and summarized down to a few bullet points per project.

When I first started keeping a work journal, I would write notes at the end of the day. The problem here was that I didn’t have a good habit of reminding myself to do this. The next day, I would sometimes struggle to remember what I did the previous day. At this point, I needed to help myself to reinforce this habit by including a bit of time at the end of the day by putting the time on my calendar.

Summaries

Summaries are important to your long term success of any project or on your career path as a TW. I found keeping a weekly journal, summarizing the daily information down to a few concise project points helped me write monthly summaries which in turn informed my long-term summaries (usually quarterly, bi-annual, or annual summaries). This is where the true magic of keeping a work journal comes to live: writing long-term summaries.

Weekly summaries

As mentioned earlier, I like to wind my work week down by setting aside 15-30 minutes to collect all my thoughts, condense all my weekly accomplishments, and plan for next week. At this point, I found that by doing this weekly exercise, I am better able to look at the bigger project picture and be able to filter out the noisy bits of my work week. 

The following is an example of a brief and simplified but accurate example of a weekly work journal:

June 26th 2023

• Summary
• Project X
• Finished writing a research project with Mike and shared it with the X team (TICKET-29330)
• Project Y
• Shared a draft on task Y (TICKET-30200)
• Friday
• Project X(TICKET-29330)
• Wrapped up the research project with Mike and had it peered reviewed by the project lead Mary
• Project Y (TICKET-30200)
• Finished my draft on task Y and shared it with the Y team (TICKET-30200)
• Misc
• Put out a few low-level fires and answered some Q/A forums
• Thursday
• Project X(TICKET-29330)
• Jess and I iterated on the research project
• Met with the X team and received project updates which we then included included in the research project notes
• Wednesday
• Project X(TICKET-29330)
• Brainstormed some new ideas for the research project we started last week
• Tuesday
• Project X(TICKET-29330)
• Continued to outline project details assigned from last week and from my notes with Mike
• Monday
• Project X (TICKET-29330)
• Met with Mike to get details on a new project from the X team

The summary section is what would get shared with my manager and other interested parties.

Tip: When tailoring your summaries, keep in mind who will consume them on a regular basis. Keep them short and concise.

Monthly summaries

At the end of every month, I summarize all my weekly summarized into a condensed high-level project review. Tip: if you keep track of project or personal metrics, now is the time to include them into your journal.
There are various methods for condensing your weekly summaries into a monthly summary. The best that I found goes something like this:

1. Review each week's summaries for their primary topics and organize that into a list for your monthly summary to categorize all your work.
2. Scrub each weekly summary for highlights and goals met.
3. Condense redundant information into one line. For example, if you spent the entire month researching and writing content, summarize this activity with just one line.
4. Include any key collaborator names that are important to making progress on your projects.
5. Repeat steps 2-4 until you have exhausted all possible high level topics.

Long period summaries

Similar to monthly summaries, at the end of each quarter, half, or year, go through your monthly summaries and condense again. Boil down to the key projects but unlike the monthly summaries, add the why statement to each item. For example, let's say for the month of June, you completed a doc project and your summary line looks like this: "Collaborated with John to finalize the X feature." At the long period summary, if this was an important point, add why it was important or what the outcome was after it was completed. For example, I would revise this bullet point to read like this: "Collaborated with John to finalize the X feature which was mission critical to this release cycle as the Client needed this document on launch day and the document received 100 pages views in the first week."

Templating

Everyone has their own workflow and your work journal should fit your needs. You may choose a minimalist approach to journaling or go for maximum detail. Either way, you may want to create a template and customize to fit those needs which you can use again and again to start a fresh journal each week. Some use templating features of their chosen platform and others copy and paste the previous week's journal and strip out the unnecessary bits.

Your weekly template can be organized any way you see fit but if chronological order of things are important, consider the following structure:

• Priority checklist (using checkboxes instead of bullets)
• Weekly summary
• Notes by day organized by category, project work, or by day

A monthly summary template may vary from month to month but the general structure usually follows that which you use in your weekly template. I like to keep all my monthly summaries in one document separated by month which then captures all the details for each project. Consider this format:

• Month
• Project X
• High level detail 1
• …
• Project Y
• High level detail 1
• …
• …

When I started condensing down to monthly summaries, my manager would limit me to 2-3 bullet points per project. Since then, I found that the level of detail may work or may not work depending on the scope and importance of the project. I still try to condense down to the good bits but I put a personal limit of 5 bullet points. Anything beyond that is probably too much detail for your consuming audience. The main point here is to condense as much as you can without sacrificing the important details.

Time Commitment

After presenting this concept of work journaling, the first question I usually get is "how much time do you spend writing all these journals?" I have a personal idea of how much time it takes me but for the first time user of this method, it will vary widely. When I first started journaling, I would spend about 15 minutes a week writing a minimalist journal. Once I moved up to a moderate detail level journal, my time spent doubled. As my habit grew stronger and stronger, time spent stayed around the 30 minute mark and my level of detail went up. I could pull out metrics, who, what, where my files were, ticket links, and when I worked on something in a quick search. At the end of each week, I would schedule myself 30 minutes to wrap up my journal, summarize, and review what I had planned for the next week.

Writing a monthly summary varies too. Depending on project activity levels, writing a monthly summary could take one to one and a half hours once a month. For long term summaries, again it would vary but for me writing a bi-annual summary, it would take me 2-3 hours once every six months. The better developed habit you have for organizing and keeping your journal would affect how quickly you can write your summaries.

In the end, having these summaries have been a great success for me as I have been able to pull out a project's status on a moment's notice, share with key stakeholders what was accomplished in any given time period, and also add lines to my resume on my key responsibilities.

Developing A Documentation Plan

In my professional experience as a technical writer, I've had the pleasure of working with several software development teams that have gone through highs and lows of successful product launches. The teams that included documentation as part of their planning process were often more successful than those who did not. This post will share a basic model for developing a documentation plan.

Planning Phase

During the planning phase, your technical writer should be present to identify any documentation needs and add a voice to the process so that end-user documentation can be included in the product life cycle. All too often, I've seen technical writers excluded from the process until the product is about 50-75% complete and then the project managers start asking questions like "Where is our documentation", "What is the status of our release notes?", or "Who is working on the documentation?" At this point, documentation will suffer as the technical writer must now go back through a bajillion documents, interview every developer and manager on the team to figure out what the minimal viable product (MVP) for documentation would be and do their best to reach that goal before release day.

Ideally, a development team would include you, the technical writer, in their planning process well before the midpoint of their project.

Setting Goals

Once the documentation set has been identified, you will need to collaborate with the subject matter experts (SMEs) to complete your doc tasks. During the initialization phase of this documentation project, you will need to complete the following items:

1. Identify who the primary and secondary SMEs are. Developers often take time off from work and you need to know who else can help contribute to this project while they are out so that you don’t get blocked or have a slowdown that could potentially delay the project.

2. Identify all the documentation components for MVP delivery and stretch goals.

3. Prioritize these doc goals so the team will know what you and they will need to focus on first.

4. Establish a timeline and due date for key components of the documentation.

5. Set documentation milestones. At what point should feature X be complete? When should feature Y be drafted? When should the release notes be published?

6. Set the paths of success and what failure would look like and include backup plans (e.g. what does 100%, 75%, and 50% complete look like).

7. Set up regular check-ins with the team to provide doc status updates, gather new information, and general project communication. This can be done as a standalone documentation meeting if the project is large or be included as an agenda item for the regular team meetings.

Project Maintenance

With the scoping and expectation phase complete, the rest of the project is a simple matter of gathering information, writing, and publishing content, right? In a perfect world, yes but we exist in a space where perfection is the enemy. In my experiences, senior technical writers should include the following in their regular process to properly communicate documentation status:

• Update associate project management tasks and timelines according to the doc project status and communicate these changes to key stakeholders. The frequency of this may be anywhere from daily to weekly depending on the size of the team, frequency of product updates, and other factors that would affect your doc plan.

• At key intervals, review the project roadmap to ensure that you and the team are hitting your milestones. Communicate any project slippage, task completion, and other general progress with key stakeholders. This communication should also include how the SMEs contributed so they can be recognized for their contributions.

• If the project is a long-term project, consider writing and publishing a monthly summary of all the completed work, where documentation energies are being spent, celebrate those who contribute to the documentation project, and highlight any interesting content traffic (e.g. wiki/web metrics, interesting search patterns, changes in viewership, etc.), and other bits of information that your team may find useful about the project.

• If you are not the primary writer…

• your team/company doesn’t have or enforce a style guide, you will need to build in some extra time to address documentation uniformity issues like tone, voice, and content structure.

• As new documents become available, ensure they are properly cross-linked with existing content and vice versa. Let the primary content creator know that you will and/or updated their content so there are no surprises.

• If a new document replaces an older one, if possible, let both documents co-exist for a brief time. Oftentimes, your users will need time to migrate off the old system and adapt to the new features. Add a banner or some sort of notice to the older document with a brief explanation, expected end of life date, and a link to the new documentation set. Sometimes you may be required to add a banner to the new document as well stating that this one replaces the older document. Include a link to the older one and a link to the release notes for further clarification. Once the older document has reached the end of life, set up a redirection feature in your wiki/web site to point to the new document and archive the older document from public view.

Salary Calculator and Negotiating

If you're like me, you often get frustrated and/or confused about how much you should be getting paid as a technical writer. The Salary Calculator by Robert Half is a great tool that takes a lot of the guess work out of salary requirements. For example, I plugged in the following:

1. Area of Specialization: "Technology & IT"
2. Job Category: "Software & Application Development"
3. Job Title: "Technical Writer"
4. State: "Oregon" (as I happen to live here currently)
5. City: "Portland"

At the writing of this article, the current salary range was $63.5k - $107.7k with the median being $76k. There should be a few things to keep in mind here with this salary range:

• Bonuses and benefits are not included
• You should add another 5-10% to your salary if you possess certain skills and/or certifications

Now that I know how much I'm worth and the fact that I feel very confident with my skills and work experience, I can confidently ask for the aforementioned salary range when applying for a new job.

If you are already employed, I found the article by Robert Half called How to Negotiate Salary After You Get a Job Offer rather useful for giving tips and advice on how to ask for more pay on the job.

Customizing Confluence: Last Modified Date

Introduction

At times of exporting content from Confluence, you may find yourself in a situation where a date stamp is required in the output files. Depending on your process for exporting content, by default, Confluence doesn't export time data (created or last updated) through its native means. If you have the budget, there are a number of plugins that can provide you with a macro to use in your documents but if you find your budget is tight, you can use the following code to create your own user macro to obtain a document's last updated date.

Required skills

You should be comfortable and/or knowledgable with the following:

• HTML
• jQuery
• Creating user macros in Confluence
• Modifying page layouts and space layouts in Confluence

Creating an user macro to display the last modified date

To create an user macro that display the last modified date, you can copy/paste the following code into your instance of Confluence:

Macro name: last-modified
Macro title: Last Modified
Description: Displays last modified date of the document.
Categories: Reporting
Macro Body Processing: No macro body
## @noparams
<span id="lastModifiedDate" style="font-size: 0.7em">Last Modified: $action.dateFormatter.formatDateTime($content.lastModificationDate)</span>


This simple little macro grabs the last modified date from Confluence and will display the value wherever you insert the user macro on your document. The font size is made to be purposely smaller so it won't be to noticeable on your document.

Modify layouts

If your process of exporting content includes the rendered HTML document, then instead of inserting a macro on every document can be replaced by updating the space layout with a little jQuery function to obtain the last updated date and insert it into the body of the wiki content element.

Note: Modifying the Content Layout of a space can be dangerous. If you remove a line from the Page Layout, you could corrupt the space and possibly make Confluence unstable. Use this method with care.

If you are using the Default Theme, insert the following code in Page Layout (Space Tools > Look and Feel > Layout > Create Custom under the Content Layouts in the Page Layout section) after the page setters:

<!-- last updated insertion -->
<script>
$(document).ready(function() {
$('div#main-content').append('<span style="font-size: 0.7em;">Last updated: ' + $('a.last-modified').text() + '</span>');
});
</script>
<!-- end last updated insertion -->

If you are using the Documentation Theme, insert the following code in the footer of the page layout:

<!-- last updated insertion -->
$(document).ready(function() {
$('div.wiki-content').append('<span style="font-size: 0.7em;">Last updated: ' + $('a.last-modified').text() + '</span>')
});
<!-- end last updated insertion -->


This method of inserting a last modified timestamp is, IMHO, the easiest and safest way to add a timestamp to every document in a space.

Managing Writers: Interview with Richard Hamilton (podcast)

I recently had a chance to listen to Tom Johnson's podcast entitled Managing Writers: Interview with Richard Hamilton and I found it to be very insightful. I totally agree that documentation metrics are difficult to nail down and pageviews aren't always the best metric (though a decent one).  I personally haven't found a good metric of productivity for tech writers. (If you have one, I'd love to hear about it.)

Documentation managers (writers or otherwise) are best served by simply staying aware of what their tech writers are doing and how heavily loaded they are on a regular basis. Having regular check-ins and one-on-ones is the best way to tell if a writer is overloaded or not.

Migrating Content From One Confluence Instance to Another

Introduction

From time to time, as a Confluence administrator, you'll be called upon to migrate a space to a new Confluence instance. This guide provides some tried and true steps to generate a list of spaces in Confluence, figure out how active a space is (so you can decide if it should be archived, migrated, or simply removed), how to find a space owner, add a warning message to a space, set a space to "read-only" mode, and delete a space.

Required skills

You should be comfortable and/or knowledgable with the following:

• HTML
• Managing Confluence space themes
• Basic Confluence administration
• Exporting and importing Confluence spaces

Migrating Confluence content

1. Generate a list of all the spaces in your old Confluence (instance). This list will be used as a checklist for tracking all the spaces that have been migrated to the new instance.
   1. To get a list of spaces, go to Spaces > Space Directory. This page will show you a list of all the spaces in your instance.
2. Start reviewing the spaces for level of activity. I believe it is safe to say that if a space hasn't had any visitors in 6+ months, then it should be marked as archived and prioritized for either removal or migration.
   1. To see the level of activity, go into the space and then Space Tools > Activity. In the Activity page, set the Period for months and review the previous six months of activity by clicking on the previous button for the month section.
   2. To archive a space, go to the space in Confluence and then Space Tools > Overview. In the Overview page, click on Edit space details button. From there, change the Status to Archived and click on the Save button.
3. Identify and speak with space owner(s) and get their permission to archive and/or migrate a space. Also ask them if the space should have a higher or lower priority for migration.
   1. To see who the space owner is, open the space and go to Space Tools > Permissions. Under Individual Users, you should typically see someone who has all permissions to the space. Another way to see who created the space is to go to the space's home page. This home page will have information about who created this page (which should be the person who created the space (i.e. the owner of the space) unless of course the Confluence administrator is responsible with the task of creating spaces.
4. Work with space owner(s) on active spaces so you don't interrupt their work and set a date for migration.
5. Add a migration warning to the space that it will be migrated on a designated date.
   1. To add a warning label to a space and the target space is using the Documentation Theme, follow these steps:
      1. Navigate to the space's Themes page (space > Space Admin > Themes).
      2. In the Messages section under Header, add the following code:
         {html}
<div style="background-color: red; color: white; padding: 5px;">This space will be migrated on <span style="color: yellow"><designated_migration_date></span></div>
{html}
      3. This will add a message on top of every page in the space and the unstylish colors will definitely grab the attention of everyone viewing the page.
      4. Note: it's a good idea to give everyone at least a two weeks notice about the migration.
6. For unvisited spaces or spaces about to be migrated, put the space into "read-only" mode.
   1. To make a space "read-only", go to Space Tools > Permissions.
   2. In the Permissions page, you should see a list of space admins and groups. It would be best to leave the permission scheme alone for the space admins but if you have a group where all users fall under, change it so it is only set to All View to checked and everything else is unchecked.
7. Export spaces on designated dates. Start with higher priority spaces and work your way down to the low priority spaces. See Export and Import a Confluence Space for instructions on how to export a space.
8. Import the exported space into the new instance. See Export and Import a Confluence Space for details on how to import a space.
9. Go into the newly imported space and confirm that everything is in proper order (content and attachments are fine, macros are working as expected, permissions are good, and so on). Note: this step may take a bit of time. I recommend that you get help from the original space owner(s) to confirm that the migration went well.
10. Change migration notice to migrated and marked for removal. Update warning of the exported space in the old instance that it has been migrated (with a link to the new space) and add a removal date.
    1. To add a removal warning, repeat the sub-steps listed in step 5.
       1. Navigate to the space's Themes page (space > Space Admin > Themes).
       2. In the Messages section under Header, add the following code:
          {html}
<div style="background-color: red; color: white; padding: 5px;">This space has been migrated to <a style="color: white; text-decoration: underline;" href="url_of_new_confluence_instance/display/<spacekey>">url_of_new_confluence_instance/display/<spacekey></a> and will be removed from this wiki on <designated_removal_date></div>
{html}
          
       3. This will add a message on top of every page in the space and the unstylish colors will definitely grab the attention of everyone viewing the page.
       4. Note: it's a good idea to give everyone at least a two weeks notice about the removal.
11. On the designated removal date, delete the space old space in the old instance of Confluence. While this is a very dangerous step, keep in mind that you have the exported zip file and the newly created space in the new instance. If anything goes wrong, you can always re-import the space back into the original Confluence instance.
• To delete a space, go to Space Tools > Overview. Click the Delete Space button. You may be prompted to enter your credentials so be ready to enter that information. Click the Ok button to start the deletion process. Depending on how big the space is, this could take a few seconds or several minutes. Check with the Time Remaining counter (I find it's mostly accurate 90% of the time but that will vary from server to server based on your server's configuration).

Tip: You may want to include a message at the top of the newly imported space in the new instance where one can find the old space in the old instance. Just use the sub-steps mentioned in either step 5 or 10 and add the necessary info to point back to the old space.

Should it be Capitalized

Every once in a while I come across fun little tidbits of knowledge. Today, I found this knowledge-nugget which guides one in how to capitalization in a title or headline.