Add nodes' lessons learned in a structured way

[jmenglund]

Location

No specific location, but see below for a discussion of where to place the information.

Change

My suggestion is that we define a simple "lessons learned template" where the nodes can briefly summarise their experiences. The headings could look something like this:

• What did we do?
• What went well?
• What could have been done better?
• What did we learn?

I think it is important to keep the text short, so we may want to put restrictions on the number of words under each section. I also think we should avoid adding lessons learned from too many nodes about the same thing.

I'm not sure where this information would be most suitable, but it could be placed under individual topics. The lessons learned regarding outreach and training for example could then be a single file with a structure looking something like this:

• Communication with stakeholders
  • FEGA Poland
    • What did we do?
    • What went well?
    • What could have been done better?
    • What did we learn?
  • FEGA Spain
    • What did we do?
    • What went well?
    • What could have been done better?
    • What did we learn?
• Creating the node's website
  • FEGA Norway
    • What did we do?
    • What went well?
    • What could have been done better?
    • What did we learn?
  • FEGA Sweden
    • What did we do?
    • What went well?
    • What could have been done better?
    • What did we learn?

Reason

• New FEGA nodes can avoid some of the misstakes that other nodes did.
• Lessons learned will complement best practices and could potentially serve as a basis for development of new best practices.
• With a defined format, the lessons learned text should be fairly easy for nodes to produce.

[malloryfreeberg]

I really like this idea! I can envision we have a simple markdown template file that any node can make a copy of and fill in the content. These "stories" can be stored individually in a subdirectory in GH, and then we can import them into any relevant part of the main website content. Each file will describe a specific experience or lesson learned. Similar to the "Tip" boxes used in the Galaxy Training Materials tutorials (example here, find a "Tip" box and click the plus sign to expand).

Having the content be expandable means less risk of experiences/lessons cluttering up the main content. Having the experiences be individual files means we can also manipulate them to create other content, easily move content around as needed, and more easily coordinate updates to the main pages.

Making this look pretty on the website might take some time playing around with the Jekyll theme, but we can create the template now (a simple file in GH) for the content that we want people to fill in. Building off of @jmenglund 's suggestion, how about:

Experience Title

<10-15 words>

FEGA Node

<name of node, e.g. FEGA Sweden, GHGA>

Author(s)

<name(s) of individual(s) who contributed to this content>

What did we do?

<Max: 100 words>

What went well?

<Max: 100 words>

What could have gone better?

<Max: 100 words>

What did we learn?

<Max: 100 words>

[jmenglund]

I'm glad that you liked my idea @malloryfreeberg!

I will try to put something together using your template when I'm back to work later this month! This will be a fun exercise to see how it works. I have some ideas of what I can write about, so it shouldn't be too hard.

Keeping the stories in individual files is an excellent idea, which I think also will make it easier for people to collaborate. For sophisticated processing of the content, you may want to consider using a YAML file header (see for example the RDMKit for inspiration).

Thumbs up also for the expandable content!

[jmenglund]

My colleague @mattiasstromberg has started to write about our experience from the end-to-end demonstrator we had earlier this year. The template seems to work quite well for us, but 100 words the for section "What did we do?" feels rather short. Can we extend it to 150 or perhaps 200?

[malloryfreeberg]

Certainly! As you are the first use case, the guidelines can definitely be tweaked as you see fit. Max 200 words still feels reasonable. Are you writing as a narrative? Or numbered steps? Or something else? Maybe some guidance on the format/structure would be useful?

[jmenglund]

Great, we will try to keep the text as short as we can!

We haven't really figured out yet how we should format the text. We started last week by just adding our thoughts as bullet points. I think we need to revise the text to make it more varied and interesting, perhaps by combining narrative writing with bulleted or numbered lists.

[M-casado]

I like the idea, and I have two suggestions:

• Besides putting the tips in specific sections, I would also recommend having a direct link to this directory where we put all of them. This link could exist at the Learn-from-current-node-implementations section.
• We could easily create a GitHub Issue template for this matter: would make easy the process of adding, editing and managing all these files in markdown format. With it, we can assign tags and tasks automatically.

[malloryfreeberg]

Update: Some nodes have drafted user experience stories here which we will start to populate in the onboarding website.