Skip to main content

Contribute knowledge

The analysis learns what's in the code. What it can't derive, it asks. When you answer a question, add know-how, or correct a chapter, every application it applies to picks it up on its next analysis. Each contribution is signed with your name.

Answer open questions​

A question is something the analysis found but couldn't explain from the sources. It might be a host nobody owns, a dependency it couldn't confirm, or a parameter that looks suspicious. Each question is asked once for the whole organization, and the evidence from every application that ran into it accumulates on it.

You'll find questions in three places: Open questions in the Knowledge Base section, grouped by the application that asked; the Questions tab of an application; and your Learning path.

To answer, click Answer, write what you know, and send it. Questions about a host get a short form instead. You say whether it's one of your applications, an external service, or an identity provider, and pick which one. Before you save, the form tells you what the answer will do. For example, from its next analysis on, the application that asked counts calls to that host as calls to the application you picked, and the question isn't asked again.

If the question doesn't matter, click Not relevant to dismiss it.

Not sure what a question means? Ask the KB about it opens a conversation where Knowledge explains the question from its evidence and from what a search finds. The conversation is shared, so everyone who opens the question sees it. You can ask up to six questions per visit. Only an answer teaches Knowledge something new, though.

Add know-how​

Know-how is what your team knows that the code doesn't say: a convention, why something is the way it is, or what to watch out for. The analysis reads it before it looks at the code of every application it reaches.

  1. Go to Explore, clear the search, and choose Norms and know-how.
  2. Click Add know-how.
  3. In Where it applies, choose the whole organization, an account, or a namespace. With a namespace, you can narrow it to one application.
  4. Write a Title (up to 120 characters) and What the analysis should know (up to 4,000 characters).
  5. Click Add.

The entry shows up in the list right away, signed with your name. The next analysis of the applications it reaches takes it into account.

Norms and instructions

You can add know-how, which describes how things are. Norms prescribe how things should be, and the analysis audits every application against them. Instructions tell the analysis where to look and which sources to use. Both are written by your organization's curators. Reach out to them, or suggest a correction on an existing entry.

Correct or add context to what you read​

Under a book chapter, a document, or a fact, click Suggest a correction or add context:

  • Correction: say what's wrong and what it should say.
  • Context: add what Knowledge should know about it.

It's saved as knowledge on that application, signed with your name, and the next analysis of the application reads it.

Correct a norm or know-how entry​

Open the entry in Norms and know-how and click Suggest a correction. The entry doesn't change until someone reviews your correction. Pending corrections are listed under the entry.

What happens to your contribution​

What a person writes is protected. An analysis never overwrites it. When new evidence contradicts something a person wrote, Knowledge opens a suggestion so someone can compare the two and decide.

Findings become action items​

When the analysis verifies a problem that matters, such as a bug, a security risk, a norm violation, or documentation that no longer matches the code, it files it as an action item on the application. Each item carries its category, severity, and evidence. It can also carry a suggested fix your team can turn into a pull request.

You triage these items like any other action item. One defect makes one item, so running the analysis again doesn't duplicate it. When a later analysis finds the problem fixed in the code, the item closes itself.

Low-severity findings stay visible in the application's facts and aren't filed as items unless your organization asks for them.

If you can't contribute​

Answering, adding know-how, and suggesting corrections run through your organization's Knowledge workflows. If you don't see those buttons, or you see a note that you need access to this organization's workflows, ask your administrator for access.