Refreshing the NetBox documentation

[jeremystretch]

I'm going to be working on restructuring and refreshing the project's documentation for the upcoming v3.3 release. My primary goal is to make it flow better from installation to data population to extension and customization, so that newcomers have a better sense of the intended deployment approaches.

Do you have any suggestions to help improve the documentation? Anything you think is missing or hard to find, or just general ideas for new and improved content.

[hagbarddenstore]

One thing that is related to the documentation that came up in a discussion with a colleague. Make the button in the footer link to the relevant page in the documentation. So if you go to the list page of say Devices, clicking on the documentation button in the footer should go to https://demo.netbox.dev/static/docs/core-functionality/devices/ I guess this requires a bit of restructuring so that you can automatically generate the link to a model.

…

Sent from my iPhone

On 25 Jul 2022, at 20:01, Jeremy Stretch ***@***.***> wrote:  I'm going to be working on restructuring and refreshing the project's documentation for the upcoming v3.3 release. My primary goal is to make it flow better from installation to data population to extension and customization, so that newcomers have a better sense of the intended deployment approaches. Do you have any suggestions to help improve the documentation? Anything you think is missing or hard to find, or just general ideas for new and improved content. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread.

[jeremystretch]

That's a neat idea, and we do something similar now with the object create/edit forms: Clicking the "?" button at top right will take you to the documentation page for that specific model. We might be able to do something similar with the footer link, however there's not always going to be an obvious landing place in the docs for every view.

[jcralbino]

I would like also to see sometimes in the documentation some examples of how to model specific situations, and explains the best approach

For example

• how to model a firewall cluster

1. we use internally checkpoint that it can use two separate management IPs, and it used some form of fhrp that is assigned to the active member. Currently I created a cluster ( under virtualisation) and assigned a cluster type for checkpoint.
2. we use also internally stormshield , that uses a unique management ip. This can be seen as a virtual chassis ? So we model it like that but without assignment of master ( to avoid interface renaming)

Although none of the above examples are using "adapted" objects that imply other uses I did not found the best way to model this

[jcralbino]

It could be interesting to see how other uses model common situations in the netbox

Device modelling

• VMware cluster
• assignment of virtual machines in VMware cluster to virtual switch port groups
• port group in VMware ?
• container modelling of pods ? Docker hosts ?

Maybe we should create a structured approach to receive all the different use cases from different users

[jeremystretch]

I would also to see sometimes in the documentation some examples of how to model specific situations

Agreed, I'd to include more content like this. The tricky bit is where to put it. I thought about adding a "How do I model..." section to address various scenarios, and linking to it from relevant points throughout the data model documentation.