Page Comparison

The most common incentive to create or edit documentation is to "scratch an itch," which is felt when we encounter a lack of information or standards around a practice. When you find a gap in the documentation, you're probably the best person to fill it. You’re encouraged to chat about your pending contribution in the #guild-handbook before creating a draft.

DRAFTS

When preparing to make changes to guidelines published Got an itch because our documentation is lacking? Fantastic, please help make it better.

Please guide your contributions by intent and the desired outcome versus detailing a process that will not happen. That means keeping things simple and letting the best interest of Axelerant be the way.

Make a DRAFT

To make changes to guidelines in https://axelerant.atlassian.net/wiki/spaces/AH or https://axelerant.atlassian.net/wiki/spaces/OA, create a copy of the target page in into /wiki/spaces/AH/pages/3034480778 or Google Docs for editing and review.

All drafts should be suffixed "DRAFT" in the page title. E.g., Benefits DRAFT. The draft version is to ensure that revisions are thought out and not perceived as rapid change.

When you’re confident DRAFT pages are good enough, submit a request to People Operations for editorial and legal review plus publishing.

When it’s time to publish the revision unless it’s a new page that can be directly moved, a designated person will copy the content from the /wiki/spaces/AH/pages/3034480778 section page or Google Doc into the target page. We’ll not replace the page itself as to not break the page links.

Video , excluding child pages.

Note: Check the revisions page to ensure we're not making a second draft: one draft, one live.

...

Rename the page with a DRAFT suffix in the page title, like Benefits DRAFT, and click Publish.

Note: Do not make your content edits yet because your first save reflects the live page, which makes future change comparisons much more manageable.

...

Alternatively, edit the page in Google Docs and create a DRAFT when ready for review.

DRAFT Edit Notifications

• https://axelerant.atlassian.net/wiki/spaces/AH edit notifications in #feed-axelerant-handbook.

• Open Axelerant edit notifications in #feed-open-axelerant.

Using IGNORE

By default, DRAFTs mean open for feedback. Yet, there are times when the draft is rapidly evolving, and comments should be held off. As such, prepend the page title with IGNORE.

...

Request a DRAFT Review

When the DRAFT page is good enough, submit to https://axelerant.atlassian.net/servicedesk/customer/portal/9/group/30 review and publish request per Handbook Reviews.

Publishing a DRAFT

There are two types of publishing: new page and content replacement.

1. For an entirely new page, publishing the draft is as easy as removing DRAFT from the page title, saving the page via Publish, and then moving the page to the appropriate location.

2. For replacing existing page content, like Being Axelerant, replace the live page content with the approved DRAFT page. Then, check and fix any quirks before saving the page via Publish. Afterward, Delete the DRAFT page.

Visit https://www.loom.com/share/e659c78dd3014b18801863ba4c6b1bda

...

for an example of moving pages and content.

Page No Longer Fits - Archiving or Deleting Content

• When live content is no longer valuable to Axelerant, prepend the title with zzz and Archive.

• When a draft page is no longer valuable to Axelerant, Delete it.

...

DRAFTs in Progress

The DRAFT pages below are not publicly accessible , yet shared here at a high level to let you know the kinds of things we’re attempting to clarify well. When they go live, they’ll be brought into via https://axelerant.atlassian.net/wiki/spaces/OA, yet are shared to give insight into what we're bringing forward or clarifying at Axelerant.

Reviews

The @admin-team of People Operations handles editorial and legal review of Axelerant guidelines, policies, and processes within the Axelerant Handbook and Open Axelerant documentation once a year, typically every January.

Dates of Latest Reviews & Updates.

Reviews & Changes Process

• Directly Responsible Individual’s (DRI) checklist for review/changing a process/guideline:

  • Demonstrate the reason for the change in the existing or new guideline process

  • Read and research relevant best practices

  • Document suggestions/concern points, using the #disc- Conversation Creator to help collect feedback. Inviting all relevant team members/stakeholders to share their suggestions in channel.

  • When the guideline change is applicable to all, then all the team members can be invited to join the disc-conversation channel, and wait for at least 2 weeks for everyone to share inputs, before finalizing the draft

  • Collate all the suggestions, and consider the suggestion which can be implemented within the given time/budget in hand. Create a Draft of the proposed guideline/process.

• Ensure the values of the organization are considered while drafting the guideline/processes. The verbiage used must be kind, inclusive, and respectful.

• When a monetary impact is expected from the suggested change in guideline/benefit - get a clear go-ahead from Ankur or Michael plus Puneet for ensuring the sustainability of the proposal.

• Share the draft with the Relevant stakeholders with clear expectations, and clear deadlines by when you choose to close/publish the final draft.

  • Relevant stakeholders might be your direct team members and other leaders

• The DRAFT copy of the guidelines must be shared with the ops-organization channel, providing a couple of weeks to share feedback on revisions.

• Mention the change effective date

• Post the deadline, and publish the draft to Confluence.

• Go-live, announce via #announcement or #general channel using @team-axelerant / @channel tags

• Share a video recap (Loom / Slack recorded video) if there’s too complex stuff that needs a simpler explanation of the process.

• Retrospect change

Page No Longer Fits - Archiving Content

...

Handbooks at Axelerant

We have the below handbooks at Axelerant.

1. The Axelerant Handbook (private) applies to everyone at Axelerant.

2. The Open Axelerant (public) applies to everyone at Axelerant.

3. The Engineering Handbook (open) applies to engineers at Axelerant.

4. The Delivery Handbook (in the Delivery section of Axelerant Handbook) applies to one or more Program(s) and projects and talks about how we deliver at Axelerant.

5. The Engagement Handbook (private)is specific to the project/engagement.

Content placement

Please choose the correct handbook to place our content based on the flowchart below.

...

It is important to reiterate that the decision will involve discrete judgment and, possibly, discussion. Use the flowchart as a reference, but in the end, apply your judgment. We are flexible in changing our stance wherever it makes sense.

Related Topics