Git Product home page Git Product logo

docs's Introduction

Giant Swarm user documentation

This is the main documentation repository for the documentation available at https://docs.giantswarm.io.

Contributing

We welcome any contributions on content to this repository in the form of pull requests!

Please review the Contribution guidelines for guidelines on suggesting changes and getting them published this repository.

If you are an employee of Giant Swarm you can get more information per intranet page with info on style and other pre-requisites.

While making changes, please use

make dev

to render the results. This serves the web content on http://localhost:1313/ by default. Please check if your changes display correctly before opening a pull request.

Search

The search functionality works since last Nov 2023 using a third-party system called Inkeep which makes use of Artificial Intelligence to index all the content of our docs and serve good results. Also, it allows to have a conversational interface to get a faster response in our wide documentation hub.

In the internal portal we have defined our docs as main source of content for the Large Language Model(LLM) instance which will be scrapped weekly to digest new content. Access is granted via OIDC and Google.

Since we use Inkeep for more uses cases the project for docs is called "Giant Swarm customer facing". There in the integration you can see our docs and the configuration keys needed to bootstrap the widget. The code that triggers the render the widget is in /src/assets/scripts/base.js and the styles are part of /static/css/inkeep.css. Most of the options for the widget are defaulted and only style has be customized to fit our docs's layout.

Diagrams

We use mermaid for diagrams. You need to annotate the page previously in the frontmatter to load the mermaid code (mermaid: true). Then you can use the shortcode {{< mermaid >}} to add the diagram code.

License

The content in this repository is licensed under the Creative Commons Attribution ShareAlike license.

For attribution, please use either:

  • Giant Swarm
  • giantswarm.io

and link, if possible, to https://www.giantswarm.io/

docs's People

Contributors

andidog avatar anvddriesch avatar axbarsan avatar calvix avatar cokiengchiara avatar gacko avatar gianfranco-l avatar josephsalisbury avatar ljakimczuk avatar luebken avatar marians avatar mproffitt avatar njuettner avatar oponder avatar oshratn avatar paurosello avatar piontec avatar pipo02mix avatar puja108 avatar quentinbisson avatar rossf7 avatar stone-z avatar t-kukawka avatar taylorbot avatar teemow avatar tuladhar avatar ubergesundheit avatar weatherhog avatar whites11 avatar zeisss avatar

Stargazers

avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Forkers

benjaminherbert socioprophet mdheller wind0r albuch stefan06ro jgilfoil webwurst

docs's Issues

link to Giant Swarm website

As far as I can see, there's no link from docs to out website, although it's linked prominently the other way around. Maybe a small link to giantswarm.io in the footer is enough?

Original Author: @eik3
Created at 24-01-2015 14:14:45
Gitlab: giantswarm/docs!49

Placement of Release Notes

Where would be a good place to publish the release notes?

A fall back would be to place them in the menu on the top level, between "Reference" and "Search".

Original Author: @marian
Created at 12-01-2015 13:11:48
Gitlab: giantswarm/docs!39

Enhance "What is Giant Swarm" article

Feedback from Dirk

  • Der erste Absatz muss noch knackiger werden. Die Abgrenzung zwischen Swarm und Docker ist mir da noch zu schwammig.
  • Im ersten Absatz würde ich 'microservices' verlinken. Zu einem Artikel von euch natürlich. An der Stelle sollte man aber trotzdem eine kleine Box einblenden in der Microservices in 2 Sätzen erklärt wird
  • Im Abschnitt zu Docker habt ihr wieder 1A Marketing-Sprech: " In contrast to traditional VM's it's an order of magnitude faster, lighter, and more fun. ;-)" -> Finde ich an dieser Stelle nicht angebracht
  • Das Beispiel swarm.json ist gut, aber dieses component-x etc. ist eher verwirrend
  • Den Microservices Absatz würde ich weiterhin in der Form streichen. Auch den Verweis auf 12 Factor App finde ich nicht optimal formuliert. Die gehen meiner Meinung nicht weiter - Sie definieren nur einige Rahmenbedingungen die es leichter machen.
  • Den Artikel vielleicht "Giant Swarm in a Nutshell" nennen

Original Author: @luebken
Created at 06-12-2014 17:53:26
Gitlab: giantswarm/docs!18

When search fails, no error message and no alert occurs

Today we had the state where the search index hasn't been created at the upstream start. (No idea why, finding out would probably hard. Restarting swarmdocs fixed it.)

This lead to search result pages being completely empty.

We should handle this case more gracefully on several levels:

  • Display an error message to the user (internal/technical problem)
  • We should make sure that we know about this and fix it before the user has to find out

Original Author: @marian
Created at 27-11-2014 16:41:20
Gitlab: giantswarm/docs!9

docs: Stopping your App the right way - handling SIGTERM

We should inform our users that processes inside docker containers should react to the SIGTERM signal in order to shutdown properly. They might have to take care of this within their applications.

For example, NodeJS: http://joseoncode.com/2014/07/21/graceful-shutdown-in-node-dot-js/

We could address this in the Docs in a variety of levels of details:

  • A troubleshooting/FAQ page like "I get a failed state when stopping my application.". There could be a highlevel explanation and links to articles like the above.
  • An article like a tutorial/guide "Stopping your App the right way - handling SIGTERM" which explains the phenomenon in a bit more detail. In addition, we could show examples (Dos/Donts) for some popular languages and of course give links to articles for other languages.
  • One article per language, like "How to handle SIGTERM in Python".

Original Author: @marian
Created at 23-01-2015 09:52:58
Gitlab: giantswarm/docs!46

Guide idea: Database with backup service

Ich würde gerne einen neuen Guide schreiben, der beispielhaft zeigt, wie man eine Datenbank in einer Giant Swarm Anwendung regelmäßig backupt.

Wir haben diese Anwendung: https://git.giantswarm.io/giantswarm/gitter-metrics/tree/master

Die Anwendung schreibt Daten in InfluxDB. Der Archiver-Dienst macht jede Stunde einen Dump davon, komprimiert ihn und lädt ihn auf S3 hoch.

Ich glaube, dass sich das als Vorlage gut auf viele andere Anwendungsfälle übertragen lässt. Der Bedarf dafür dürfte da sein, denn ohne Backup ist eine Datenbank auf Giant Swarm (und auch sonstwo) keine gute Idee.

Wir können natürlich unser obiges InfluxDB-Beispiel für den Guide nehmen. Wäre es evtl. besser, den Guide mit einer populäreren Datenbank (MySQL) zu bauen?

Meinungen willkommen. Ping @luebken @puja

Original Author: @marian
Created at 08-01-2015 09:12:49
Gitlab: giantswarm/docs!38

docs: Improvements for Getting Started, especially JSON expanation

Feedback from Sebastian Cohnen (tisba) on http://docs.giantswarm.io/installation/gettingstarted/

  • Meaning of swarm.json "domains" attribute was not clear, even in reference page it's not really clear
  • JSON could be explained better right on that page. Reference page wasn't too helful, either.
  • Meaning of "ports" in helloworld not clear either
  • Pre-defined domain name "helloworld.alpha.giantswarm.io" is problematic, since this is likely taken by other users. Make this dynamic via JavaScript!
  • curl request uses no port (= Port 80) while the swarm JSON uses 8000. Same goes for http://docs.giantswarm.io/installation/gettingstarted2/
  • Link to "Part 2" at the bottom could be more inviting

Original Author: @marian
Created at 05-12-2014 16:24:54
Gitlab: giantswarm/docs!16

docs: Frequently asked questions / Solving common problems

It shows more and more that some questions from users come in repeatedly. We might want to answer these questions before them having to ask, plus we might want to be able to point to a URL instead of writing the same answer several times.

There are several common approaches for this.

  • FAQs (all on one page) - Allows for a number of questions, users can scan multiple questions and answers at once. Length of answers is limited, more verbose answers including longer code snippets should be given elsewhere and linked to.
  • Knowledge base: Usually a collection of articles with search, maybe additional functions like tagging, user comments, user feedback/rating.

For the beginning I would vote for having one FAQ page, trying to provide most important long answers in tutorials and reference pages in the docs.

We have to keep in mind that users might also expect FAQs to answer questions like "Can I host database X on Giant Swarm" or "Can I do rolling deployment?", where the answer reveals a lot about the status of our product.

Original Author: @marian
Created at 24-01-2015 14:47:02
Gitlab: giantswarm/docs!50

docs: Need a place for "Running X on Giant Swarm" tips/notes

Our users and we ourselves are collecting more and more information on what to take care of when running a specific piece of some stack on Giant Swarm.

Example:

Python buffers STDOUT output when there is no terminal connected, so lines printed from a python script won't show up in Docker logs for a while. Unless python is called with the -u switch.

If we had a place to document this, this could become a very valuable knowledge base of numerous small articles.

Most likely we should integrate this into our search in order to make that content accessible. Having it indexed by Google would also pretty much be a must-have.

This type of content could (should) also be user-generated, otherwise it would be difficult to come up with the required variety of articles covering many different stacks.

A comment function (maybe standard Disqus) could help other users to keep the information useful, point out errors, alternative solutions etc.

As an editing format, Markdown would probably work pretty well.

Original Author: @marian
Created at 21-12-2014 13:35:07
Gitlab: giantswarm/docs!34

Example swarm.json for Databases

From Bumi:

Ein paar mer Beispiele an swarm.json wären hilfreich. z.B. für bekannte docker images und stacks. War mir nicht sicher wie ich z.B. postgres verwende und wie und welche env vars gesetzt sind/werden auf die ich zugreifen kann.

I would propose a simple starter example with top databases we see as a good choice for Giant Swarm.

First thought: mysql, postgres, mongo, redis.

Original Author: @luebken
Created at 06-01-2015 09:54:49
Gitlab: giantswarm/docs!36

Rails Guide is currently broken, needs fixing

The Ruby on Rails guide at http://docs.giantswarm.io/guides/ruby_on_rails/ currently doesn't work.

The problem can be reproduced by following the first four lines of code:

git clone https://github.com/giantswarm/sample_app_rails_4
cd sample_app_rails_4/
git checkout dockerize
fig up

The root cause seems to be the fact that the base image no uses Ruby version 2.2.0, which doesn't match the settings in the Gemfile.

Original Author: @marian
Created at 20-01-2015 17:53:21
Gitlab: giantswarm/docs!44

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.