build details

Show: section status errors & todos local changes recent changes last change in-page changes feedback controls

The Knowledge and Activity Graph Environment

Modified 2020-03-04 by Susi

Basics

Modified 2020-03-04 by Susi

Every page, on every book, should have a ‘Knowledge Box’ - also called ‘Knowledge and Activity Graph’. It’s the blue box you see above. In markdown, a knowledge box looks like this:

<div class='requirements' markdown="1">

Requires: Important prerequisite XY

Requires: ...

Results: Infinite wisdom

</div>

Purpose

Modified 2020-03-04 by Susi

Knowledge boxes give structure to the duckumentation. How do you know where to start? For example by following back links in knowledge boxes! Or by having an automated system follow back those references for you.

Also, imagine if dead references or circular dependencies were detected automatically. Authors could fix this right away, and you would have an easier time navigating the duckumentation. So: Add a knowledge box!

Guidelines

Modified 2020-03-04 by Susi

Here are dos and don’ts how to write useful knowledge boxes:


One knowledge box per page. (Might change in the future.)

Organize your pages in a way that one knowledge box per page makes sense. Optimally, one page should be about one distinct topic, or describe how to create one distinct thing. You can use most of the existing duckumentation as reference for a good “topic granularity”.


Use ‘Requires:’, ‘Recommended:’ and ‘Results:’ markers.

Start each line in a knowledge box with one of them.

In “Requires:” lines, link to pages that provide the requirement whenever possible.


Link only to CSS-identifiers of other pages, not specific sections on that page. (This might change in the future.)


One requirement or result per line.


A list of multiple requirements in one line.

Do not: (unknown ref opmanual_duckiebot/setup-duckiebot)

previous warning next (17 of 18) index
warning
I will ignore this because it is an external link. 

 > I do not know what is indicated by the link '#opmanual_duckiebot/setup-duckiebot'.

Location not known more precisely.

Created by function n/a in module n/a.


Use short descriptive texts, with good keywords that identify the requirement or result.


Optimal: Use the same description as in other knowledge boxes, when referring to the same entity. (Exception: If the other page’s description violates these guidelines.)


Long texts, with many unrelated keywords.

Do not:

Results: A correctly configured Duckiebot SD card in configuration DB18. After assembling the Duckiebot, this will allow you to start it, connect to the internet, and get going.

Requires: Software-X, with all requirements for the ROS example


Put all text that does not directly describe the requirement between round brackets **. Omit unnecessary words.

Do:

Results: A configured Duckiebot SD card in configuration DB18. (After assembling the Duckiebot, this will allow you to start it, connect to the internet, and get going.)

Requires: Software-X ( with all requirements for the ROS example)


For estimated time needed, use a ‘Requires:’ marker.

For example:

 Requires: Approximately 1 hour 30 minutes.

(“1h30”, or “1h, 30 min” works as well.)


If you want, you can use the instructions here(Pointer to beta/draft material that was removed - instructions-refer-to-data)

previous warning (18 of 18) index
warning
This link points to beta/draft material removed

Location not known more precisely.

Created by function n/a in module n/a.
to pick a name of an entity that the EOD system knows already, from the data files, or add a new entity there via pull request.


** This might change in the future.