Groot Documentation #113
Groot Documentation #113
Conversation
There was a problem hiding this comment.
My recommendation is to slow down and think like someone that doesn't know anything about this. It skips over details and actually introducing the concepts you're explaining how to enable. At the point someone clicks on this article, they might not even know what groot is, so explain it to them. They probably have only a cursory understanding of a BT, so show how to edit it and the structure of it.
|
@gramss what's the story here? |
when included manually it always has a wired offset to the top respective to the iframe.. but there is no such margin defined through a css in either of the objects.. unwanted to throw out groot but I have no nice solution currently.. displaying always underneath of each other isn't that nice..
|
Okay. So I went through all your comments and created a new, more detailed draft. I'm unsure if this is worthy a gif or just some text describing how to properly interact with the editing interface of Groot. I'm eager to listen what you think of this new draft. |
Gifs and images are always good!
Agreed, that's a necessary element for a full look at Groot. It could be split into 2 tutorials: once covering the groot monitoring and another for behavior tree editing with groot. I think that might help your organization as well since the first draft of this kind of mixed them both together. |
There was a problem hiding this comment.
I stopped reading about half way through, this needs alot of work.
Please, please, please slow down. You fail to do alot of basics and just jump into things without ever explaining or introducing them (but then talk at length of things that aren't relevant for groot). Remember what you're writing: a tutorial about using groot. You're not introducing all the concepts of behavior trees. Link to the BT concepts at the start and at that point, you can assume knowledge of behavior tree basics, but nothing about BT.CPP/Groot.
An introduction section should start the document. In this section, we should introduce what we're going to do, why we're doing it, the tools used to do it, and any general notes relevant to all of them.
Every subsequent section should at least have an introduction paragraph explaining what this section is going to do and examples of why we do this. You just jump right into things with no context or explanation.
Every instruction should have a detailed explanation of what you're doing and why. If you load a palette, the least you should do is explain what a palette is and what it is used for. These are not obvious things.
I think it would help you alot to walk away from this for a few days and then come back with fresh eyes. Imagine you're writing this document for someone that knows nothing about groot, palettes, editing BT files, etc. Introduce it like you'd want someone to explain a new technology to you.
In other words, slow down, be linear in your thoughts - don't jump around, and be complete. I think it would help you alot if you thought of every section as a new page with a new concept / idea. They should stand alone (except for what you introduce in the section intro) and not bleed into each other. They should individually be enough for someone without knowledge of groot / BT.CPP to do the basic tutorial task you're setting out.
Section Intro
What are we doing here, why do we need it, what tools use it, relevant context
Section A
intro paragraph about what we're doing, why, and the goal at the end of it
start section
any "do this" list should have explained directly before or after any context required to understand the random steps you're having them do
show visualizations at keys steps of interest
End of section should complete the exercise by completing whatever you set out in the intro paragraph
Section ...
intro paragraph about what we're doing, why, and the goal at the end of it
start section
any "do this" list should have explained directly before or after any context required to understand the random steps you're having them do
show visualizations at keys steps of interest
End of section should complete the exercise by completing whatever you set out in the intro paragraph
| @@ -53,6 +53,7 @@ Parameters | |||
| Description | |||
| List of behavior tree node shared libraries. | |||
|
|
|||
| Consider checking out the :ref:`groot_introduction` tutorial for using this feature. | |||
There was a problem hiding this comment.
Remove this comment, that's not really on topic. This is just a list of the libraries valid, which has nothing to do specifically with groot.
| @@ -32,6 +32,7 @@ Switching bt-xmls on the fly through a new goal request is also included. | |||
| This is all done without breaking any APIs. | |||
| Enabled by default. | |||
|
|
|||
| Check out our Groot tutorial! | |||
There was a problem hiding this comment.
You broke the formatting https://552-240847415-gh.circle-artifacts.com/0/html/migration/Foxy.html please generate the website locally and validate things.
There was a problem hiding this comment.
Also, add a link to the tutorial above.
| @@ -32,6 +32,7 @@ Switching bt-xmls on the fly through a new goal request is also included. | |||
| This is all done without breaking any APIs. | |||
There was a problem hiding this comment.
Switching bt-xmls on the fly through a new goal request is also included. is still not relevant to groot, remove,.
| @@ -32,6 +32,7 @@ Switching bt-xmls on the fly through a new goal request is also included. | |||
| This is all done without breaking any APIs. | |||
There was a problem hiding this comment.
More context is required here. "Editing" should not be capitalized.
|
Working on bringing this to the documentation today. Closing and will reopen new PR once complete |
Spin off from #87