Update job writing guide docs

[mtuchi]

Short Description

Improve job writing guide docs by grouping into smaller topics and add warning message on Referencing credentials in job code section. [See advanced concept page]

Closes #714

Details

• Group job writing guide content into specific topic files and update sidebar
• Add a warning about Referencing credential secretes in job code

AI Usage

Please disclose how you've used AI in this work (it's cool, we just want to
know!):

• Code generation (copilot but not intellisense)
• Learning or fact checking
• Strategy / design
• Optimisation / refactoring
• Translation / spellchecking / doc gen
• Other
• I have not used AI

You can read more details in our
Responsible AI Policy

[mtuchi]

Hey @hunterachieng Please review my pr and share your feedback, See my quick walk through video here

[josephjclark]

This PR confused me a bit until I figured out what you were doing!

Generally I approve, I think it's great. Just a couple of suggestions before I'm ready to merge

[josephjclark]

You know what @mtuchi, I just was just taking a final look over this and the menu is now like this:

Write Jobs
  - Job Writing Guide
  - Security Considerations

It's a bit strange to have just two submenus, and "Write Jobs" and "Job Writing Guide" are basically the same

So! What if we remove Job Writing Guide and re-parent each section under Write Jobs? That's way cleaner, and the Security page becomes just another section of the guide.

[mtuchi]

It's a bit strange to have just two submenus, and "Write Jobs" and "Job Writing Guide" are basically the same

So! What if we remove Job Writing Guide and re-parent each section under Write Jobs? That's way cleaner, and the Security page becomes just another section of the guide.

Yeah totally agree @josephjclark , let me do that

[mtuchi]

@josephjclark
I have added all job writing sections under Write Jobs category

job-write.mp4

[josephjclark]

@mtuchi something is up here!

On docs.openfn.org I see:

• Input and Output
• Javascript Tips
• Job Examples
• Code Snippets
• Handling Images

None of which I see on the local branch. I think the pages are still there, we just lost the menu links

When I asked to consolidate the menu I think all those sections were missing and I wrongly thought they were consolidated into the guide. But I don't think that's right? I think they're just lost!

I think it's OK to have all these things in the menu, at the same level, and you're right to expand the guide into multiple pages. I just want to make sure nothing is lost.

Some of these pages we can consolidate, and some probably ought to be removed. But this was supposed to be a small restructure and I'm gonna resist the temptation to do too much.

Please restore the structure so that all pages are visible (I'd merge Operations and State and Input and Output State.

Maybe when that's done I'll take an error to prune some really out of date stuff 🤔 I do have plans to do a lot of work here - I just don't have the time!

[mtuchi]

Hey @josephjclark thank you for flagging this, i will investigate tomorrow morning

[mtuchi]

Hiya @josephjclark i found the missing pages that were removed from the sidebar and added them back. I have also merged the contents of operation-and-state into state Please have a look

[josephjclark]

Phew, these docs need a total overhaul. The closer I look the more outdated things are :(

I've made a tweak to restore some more missing content around operations.

[josephjclark]

@mtuchi can you give this a sanity check and then merge if it runs OK?