From cd6d8e37e00c3f8e85ce3afcef60f39184cbae5c Mon Sep 17 00:00:00 2001 From: Nikolay Boshnakov Date: Wed, 19 Oct 2022 13:06:58 +0300 Subject: [PATCH 1/2] Updated the contributor guide --- website/community/_index.md | 3 + .../contribute/10_code/_index.md | 2 +- .../10_organisation/_index.md | 8 +- .../20_formatting_guide/_index.md | 13 +-- .../20_documentation/25_markup/_index.md | 8 +- .../20_documentation/40_style_guide/_index.md | 80 ++++++++++++------- .../40_style_guide/concept_template.md | 7 +- .../40_style_guide/reference_template.md | 9 ++- .../40_style_guide/task_template.md | 14 +++- .../20_documentation/45_images/_index.md | 51 ++++++++++++ .../contribute/20_documentation/_index.md | 3 +- .../contribute/30_community/_index.md | 42 ---------- 12 files changed, 144 insertions(+), 96 deletions(-) create mode 100644 website/documentation/contribute/20_documentation/45_images/_index.md delete mode 100644 website/documentation/contribute/30_community/_index.md diff --git a/website/community/_index.md b/website/community/_index.md index 7285cffb..f64176cf 100644 --- a/website/community/_index.md +++ b/website/community/_index.md @@ -25,3 +25,6 @@ The recordings are published on the [Gardener Project YouTube channel](https://w

Google Calendar

+### Presenting a Topic + +If there is a topic you would like to present, message us in our slack channel or get in touch with [Jessica Katz](mailto:jessica.katz@sap.com). \ No newline at end of file diff --git a/website/documentation/contribute/10_code/_index.md b/website/documentation/contribute/10_code/_index.md index 5c2b548f..2171c8c4 100644 --- a/website/documentation/contribute/10_code/_index.md +++ b/website/documentation/contribute/10_code/_index.md @@ -1,5 +1,5 @@ --- -title: Code +title: Contributing Code url: /contribute/code/ --- diff --git a/website/documentation/contribute/20_documentation/10_organisation/_index.md b/website/documentation/contribute/20_documentation/10_organisation/_index.md index 43da06b0..96500335 100644 --- a/website/documentation/contribute/20_documentation/10_organisation/_index.md +++ b/website/documentation/contribute/20_documentation/10_organisation/_index.md @@ -14,7 +14,7 @@ The Gardener project implements the *documentation-as-code* paradigm. Essentiall Documentation that can be affiliated to component is hosted and maintained in the component repository. -A recommended template for organizing documentation sources is to place them all in a `docs` folder and organize it there per role activity. For example: +A template for organizing documentation sources is to place them all in a `docs` folder and organize it there per role activity. For example: ``` repositoryX @@ -27,7 +27,7 @@ repositoryX |_ deployment ``` -Do not use folders just because they are in the template. Stick to the predefined roles and corresponding activities for naming convention. A system makes it easier to maintain and get oriented. +Do not use folders just because they are in the template. Stick to the predefined roles and corresponding activities for naming convention. A system makes it easier to maintain and get oriented. While recommended, this is not a mandatory way of organizing the documentation. - User: `usage` - Operator: `operations` @@ -41,11 +41,11 @@ Do not use folders just because they are in the template. Stick to the predefine The Gardener website is one of the multiple optional publishing channels where the source material might end up as documentation. We use docforge and automated integration and publish process to enable transparent change management. -To have documentation published on the website it is necessary to use the docforge manifests available at [gardener/documentation/.docforge] adn register a reference to your documentation. +To have documentation published on the website it is necessary to use the docforge manifests available at [gardener/documentation/.docforge](https://github.com/gardener/documentation/tree/master/.docforge) and register a reference to your documentation. {{% alert color="info" title="Note" %}} This is work in progress and we are transitioning to a more transparent way of integrating component documentation. This guide will be updated as we progress. {{% /alert %}} These manifests describe a particular publishing goal, i.e. using Hugo to publish on the website, and you will find out that they contain Hugo-specific front-matter properties. -Consult with the documentation maintainers for details. Use the gardener channel in slack or open a PR. \ No newline at end of file +Consult with the documentation maintainers for details. Use the gardener channel in [slack](https://kubernetes.slack.com/messages/gardener) or [open a PR](https://github.com/gardener/documentation/pulls). \ No newline at end of file diff --git a/website/documentation/contribute/20_documentation/20_formatting_guide/_index.md b/website/documentation/contribute/20_documentation/20_formatting_guide/_index.md index 8cb4e9b0..0694ed18 100644 --- a/website/documentation/contribute/20_documentation/20_formatting_guide/_index.md +++ b/website/documentation/contribute/20_documentation/20_formatting_guide/_index.md @@ -4,11 +4,11 @@ title: Formatting Guide This page gives writing formatting guidelines for the Gardener documentation. For style guidelines, see the [Style Guide](../40_style_guide/_index.md). -These are guidelines, not rules. Use your best judgment, and feel free to -propose changes to this document in a pull request. +These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. * [Formatting of Inline Elements](#formatting-of-inline-elements) * [Code Snippet Formatting](#code-snippet-formatting) +* [Related Links](#related-links) ## Formatting of Inline Elements @@ -118,14 +118,14 @@ Another thing to keep in mind is that markdown links do not work in [shortcodes] ## Code Snippet Formatting -### Don't include the command prompt +### Don't Include the Command Prompt | Do | Don't | |:---|:---| | `kubectl get pods` | `$ kubectl get pods` | -### Separate commands from output +### Separate Commands from Output Verify that the pod is running on your chosen node: @@ -154,7 +154,10 @@ kubectl describe pod - ### Versioning Kubernetes examples Make code examples and configuration examples that include version information consistent with the accompanying text. Identify the Kubernetes version in the **Prerequisites** section. + +## Related links +* [Style Guide](../40_style_guide/_index.md) +* [Contributors Guide](../_index.md) \ No newline at end of file diff --git a/website/documentation/contribute/20_documentation/25_markup/_index.md b/website/documentation/contribute/20_documentation/25_markup/_index.md index 85357387..25c24bc7 100644 --- a/website/documentation/contribute/20_documentation/25_markup/_index.md +++ b/website/documentation/contribute/20_documentation/25_markup/_index.md @@ -2,7 +2,7 @@ title: Markdown --- -Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown +Hugo uses [Markdown](https://www.markdownguide.org/) for its simple content format. However, there are a lot of things that Markdown doesn't support well. You could use pure HTML to expand possibilities. A typical example is reducing the original dimensions of an image. @@ -12,4 +12,8 @@ a publishing platform mechanisms, such as Hugo's layouts. Considering that the s might be published by multiple platforms you should be considerate in using markup that may bind it to a particular one. -We support the use of certain shortcodes. You can find more about the currently supported shortcodes and their documentation [here](../30_shortcodes/_index.md). +For the same reason, avoid inline scripts and styles in your content. If you absolutely need to use them and they are not working as expected, please create a documentation issue and describe your case. + +{{% alert color="info" title="Tip" %}} +Markdown is great for its simplicity but may be also constraining for the same reason. Before looking at HTML to make up for that, first check the [shortcodes](https://github.com/gardener/documentation/blob/master/website/documentation/contribute/20_documentation/30_shortcodes/_index.md) for alternatives. +{{% /alert %}} diff --git a/website/documentation/contribute/20_documentation/40_style_guide/_index.md b/website/documentation/contribute/20_documentation/40_style_guide/_index.md index ce44659a..a13ec925 100644 --- a/website/documentation/contribute/20_documentation/40_style_guide/_index.md +++ b/website/documentation/contribute/20_documentation/40_style_guide/_index.md @@ -3,11 +3,11 @@ Title: Style Guide --- This page gives writing style guidelines for the Gardener documentation. For formatting guidelines, see the [Formatting Guide](../20_formatting_guide/_index.md). -These are guidelines, not rules. Use your best judgment, and feel free to -propose changes to this document in a pull request. +These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a Pull Request. * [Structure](#structure) * [Language and Grammar](#language-and-grammar) +* [Related Links](#related-links) ## Structure @@ -28,67 +28,87 @@ See the [Contributors Guide](https://github.com/gardener/documentation/blob/mast When creating a topic, you will need to follow a certain structure. A topic generally comprises of, in order: -* [Metadata](#metadata) (Specific for `.md` files in Gardener) - Additional information about the topic. +* [Metadata](#front-matter) (Specific for `.md` files in Gardener) - Additional information about the topic -* Title - A short, descriptive name for the topic. +* Title - A short, descriptive name for the topic -* Content - The main part of the topic. It contains all the information relevant to the user. +* Content - The main part of the topic. It contains all the information relevant to the user * Concept content: [Overview, Relevant headings](concept_template.md) * Task content: [Overview, Prerequisites, Steps, Result](task_template.md) * Reference content: [Relevant headings](reference_template.md) -* Related Links (Optional) - A part after the main content that contains links that are not a part of the topic, but are still connected to it. +* Related Links (Optional) - A part after the main content that contains links that are not a part of the topic, but are still connected to it You can use the provided content description files as a template for your own topics. -### Metadata +### Front Matter -Metadata is information housed in a specific section of the `.md` files used for the Gardener documentation. It can contain: -* Title - A short, descriptive name for the topic. -* Description - A succint summary of the topic's content. Must not include the title or repeat content from the topic. -* Other elements such as weight, creation date, author and tags. +[Front matter](https://gohugo.io/content-management/front-matter) is metadata applied at the head of each content Markdown file. It is used to instruct the static site generator build process. The format is YAML and it must be enclosed in leading and trailing comment dashes (`---`). Sample codeblock: -``` +```yaml --- -Title: -Description: -Weight: +title: Getting Started +Description: Guides to get you accustomed with Gardener +Weight: 10 --- ``` +There are a number of [predefined](https://gohugo.io/content-management/front-matter#predefined) front matter properites, but not all of them are considered by the layouts developed for the website. The most essential ones to consider are: +- `title` the content title that will be used as page title and in navigation structures. +- `weight` a positive integer number that controls the ordering of the content in navigation structures. +- `description` describes the content. For some content types such as documentation guides, it may be rendered in the UI. +- `url` if specified, it will override the default url constructed from the file path to the content. Make sure the url you specify is consistent and meaningful. Prefer short paths. Do not provide redundant URLs! +- `categories` specifies the type of user the topic is aimed towards. Currently only used in the public website. + ``` + categories: + - Users + - Operators + - Developers + ``` + While this section will be automatically generated if your topic has a title header, adding more detailed information helps other users, developers and technical writers better sort, classify and understand the topic. By using a metadata section you can also skip adding a title header or overwrite it in the navigation section. +### Alerts + +If you want to add a note, tip, or a warning to your topic, use the templates provides in the [Shortcodes](../30_shortcodes/_index.md#alert) documentation. + +### Images + +If you want to add an image to your topic, it is recommended to follow the guidelines outlined in the [Images](../45_images/_index.md) documentation. + ### General Tips -* Try to create a succint title and an informative description for your topics. -* If a topic feels too long, it might be better to split it into a few different ones. -* Avoid having have more than ten steps in one a task topic. -* When writing a tutorial, link the tasks used in it instead of copying their content. +* Try to create a succint title and an informative description for your topics +* If a topic feels too long, it might be better to split it into a few different ones +* Avoid having have more than ten steps in one a task topic +* When writing a tutorial, link the tasks used in it instead of copying their content ## Language and Grammar ### Language -* Gardener documentation uses US English. -* Keep it simple and use words that non-native English speakers are also familiar with. -* Use the [Merriam-Webster Dictionary](https://www.merriam-webster.com/) when checking the spelling of words. +* Gardener documentation uses US English +* Keep it simple and use words that non-native English speakers are also familiar with +* Use the [Merriam-Webster Dictionary](https://www.merriam-webster.com/) when checking the spelling of words ### Writing Style -* Write in a conversational manner and use simple present tense. -* Be friendly and refer to the person reading your content as "you", instead of standard terms such as "user". -* Use an active voice - make it clear who is performing the action. +* Write in a conversational manner and use simple present tense +* Be friendly and refer to the person reading your content as "you", instead of standard terms such as "user" +* Use an active voice - make it clear who is performing the action ### Creating Titles and Headers -* Use [title case](https://titlecaseconverter.com/words-to-capitalize/) when creating titles or headers. -* Avoid adding additional formatting to the title or header. -* Concept and reference topic titles should be simple and succint. -* Task and tutorial topic titles begin with a verb. +* Use [title case](https://titlecaseconverter.com/words-to-capitalize/) when creating titles or headers +* Avoid adding additional formatting to the title or header +* Concept and reference topic titles should be simple and succint +* Task and tutorial topic titles begin with a verb ## Related links * [Formatting Guide](../20_formatting_guide/_index.md) -* [Contributors Guide](https://github.com/gardener/documentation/blob/master/website/documentation/contribute/_index.md) +* [Contributors Guide](../_index.md) +* [Shortcodes](../30_shortcodes/_index.md) +* [Images](../45_images/_index.md) * [SAPterm](https://www.sapterm.com/) \ No newline at end of file diff --git a/website/documentation/contribute/20_documentation/40_style_guide/concept_template.md b/website/documentation/contribute/20_documentation/40_style_guide/concept_template.md index 5aa55285..18f23ea7 100644 --- a/website/documentation/contribute/20_documentation/40_style_guide/concept_template.md +++ b/website/documentation/contribute/20_documentation/40_style_guide/concept_template.md @@ -4,6 +4,7 @@ Description: Describes the contents of a concept topic --- # Concept Title +(the topic title can also be placed in the frontmatter) ## Overview This section provides an overview of the topic and the information provided in it. @@ -12,11 +13,11 @@ This section provides an overview of the topic and the information provided in i This section gives the user all the information needed in order to understand the topic. ### Relevant subheading -This adds information that belongs to the topic discussed in the parent heading +This adds additional information that belongs to the topic discussed in the parent heading. ## Relevant heading 2 This section gives the user all the information needed in order to understand the topic. ## Related Links -* [Link 1]() -* [Link 2]() +* [Link 1](./page.md) +* [Link 2](./page.md) diff --git a/website/documentation/contribute/20_documentation/40_style_guide/reference_template.md b/website/documentation/contribute/20_documentation/40_style_guide/reference_template.md index ba95d117..5a2b0462 100644 --- a/website/documentation/contribute/20_documentation/40_style_guide/reference_template.md +++ b/website/documentation/contribute/20_documentation/40_style_guide/reference_template.md @@ -4,15 +4,16 @@ Description: Describes the contents of a reference topic --- # Topic Title +(the topic title can also be placed in the frontmatter) ## Content This section gives the user all the information needed in order to understand the topic. | Content Type | Definition | Example| |:----|:-----|:-----| -| Name 1 | Definition of Name 1 | [Relevant link]() | -| Name 2 | Definition of Name 2 | [Relevant link]() | +| Name 1 | Definition of Name 1 | [Relevant link](./page.md) | +| Name 2 | Definition of Name 2 | [Relevant link](./page.md) | ## Related Links -* [Link 1]() -* [Link 2]() +* [Link 1](./page.md) +* [Link 2](./page.md) diff --git a/website/documentation/contribute/20_documentation/40_style_guide/task_template.md b/website/documentation/contribute/20_documentation/40_style_guide/task_template.md index 47da3256..dfe1cfaf 100644 --- a/website/documentation/contribute/20_documentation/40_style_guide/task_template.md +++ b/website/documentation/contribute/20_documentation/40_style_guide/task_template.md @@ -4,6 +4,7 @@ Description: Describes the contents of a task topic --- # Task Title +(the topic title can also be placed in the frontmatter) ## Overview This section provides an overview of the topic and the information provided in it. @@ -13,12 +14,19 @@ This section provides an overview of the topic and the information provided in i * Prerequisite 2 ## Steps +Avoid nesting headings directly on top of each other with no text inbetween. +1. Describe step 1 here +1. Describe step 2 here + +### You can use smaller sections within sections for related tasks +Avoid nesting headings directly on top of each other with no text inbetween. 1. Describe step 1 here 1. Describe step 2 here ## Result -Screenshot of the final status once all the steps have been followed. +Screenshot of the final status once all the steps have been completed. ## Related Links -* [Link 1]() -* [Link 2]() +Provide links to other relevant topics, if applicable. Once someone has completed these steps, what might they want to do next? +* [Link 1](./task_template.md) +* [Link 2](./task_template.md) diff --git a/website/documentation/contribute/20_documentation/45_images/_index.md b/website/documentation/contribute/20_documentation/45_images/_index.md new file mode 100644 index 00000000..a5a0353b --- /dev/null +++ b/website/documentation/contribute/20_documentation/45_images/_index.md @@ -0,0 +1,51 @@ +--- +title: Working with Images +aliases: ["/docs/guides/contributors/content/images"] +weight: 15 +--- + +Using images on the website has to contribute to the aestethics and comprehendability of the materials, with uncompromised experience when loading and browsing pages. That concerns crisp clear images, their consistent layout and color scheme, dimensions and aspect ratios, flicker-free and fast loading or the feeling of it, even on unreliable mobile networks and devices. + +## Image Production Guidelines + +A good, detailed reference for optimal use of images for the web can be found at web.dev's [Fast Load Times](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/image-optimization?hl=en) topic. The following summarizes some key points plus suggestions for tools support. + +You are strongly encouraged to use **vector images** (SVG) as much as possible. They scale seamlessly without compromising the quality and are easier to maintain. + +If you are just now starting with SVG authoring, here are some tools suggestions: [Figma](https://www.figma.com/) (online/Win/Mac), [Sketch](https://www.sketch.com/) (Mac only). + +For **raster images** (JPG, PNG, GIF), consider the following requirements and choose a tool that enables you to conform to them: +- Be mindful about image size, the total page size and loading times. +- Larger images (>10K) need to support _progressive rendering_. Consult with your favorite authoring tool's documentation to find out if and how it supports that. +- The site delivers the optimal media content format and size depending on the device screen size. You need to provide several variants (large screen, laptop, tablet, phone). Your authoring tool should be able to resize and resample images. Always save the largest size first and then downscale from it to avoid image quality loss. + +If you are looking for a tool that conforms to those guidelines, [IrfanView](https://www.irfanview.com/) is a very good option. + +**Screenshots** can be taken with whatever tool you have available. A simple Alt+PrtSc (Win) and paste into an image processing tool to save it does the job. If you need to add emphasized steps (1,2,3) when you describe a process on a screeshot, you can use [Snaggit](https://www.techsmith.com/screen-capture.html). Use red color and numbers. Mind the requirements for raster images laid out above. + +**Diagrams** can be exported as PNG/JPG from a diagraming tool such as Visio or even PowerPoint. Pick whichever you are comfortable with to design the diagram and make sure you comply with the requirements for the raster images production above. Diagrams produced as SVG are welcome too if your authoring tool supports exporting in that format. In any case, ensure that your diagrams "blend" with the content on the site - use the same color scheme and geometry style. Do not complicate diagrams too much. The site also supports [Mermaid](https://mermaid-js.github.io/mermaid/#/) diagrams produced with markdown and rendered as SVG. You don't need special tools for them, but for more complex ones you might want to prototype your diagram wth Mermaid's [online live editor](https://mermaidjs.github.io/mermaid-live-editor), before encoding it in your markdown. More tips on using Mermaid can be found in the [Shortcodes](https://github.com/gardener/documentation/blob/master/website/documentation/contribute/20_documentation/30_shortcodes/_index.md#mermaid) documentation. + +## Using Images in Markdown + +The standard for adding images to a topic is to use markdown's `![caption](image-path)`. If the image is not showing properly, or if you wish to serve images close to their natural size and avoid scaling, then you can use HTML5's `` tag. + +Example: +```html + + + + + + + + + + +``` + +When deciding on image sizes, consider the breakpoints in the example above as maximum widths for each image variant you provide. Note that the site is designed for maximum width 1200px. There is no point to create images larger than that, since they will be scaled down. + +For a nice overview on making the best use of responsive images with HTML5, please refer to the [Responsive Images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) guide. \ No newline at end of file diff --git a/website/documentation/contribute/20_documentation/_index.md b/website/documentation/contribute/20_documentation/_index.md index cd634c15..7ce67fd1 100644 --- a/website/documentation/contribute/20_documentation/_index.md +++ b/website/documentation/contribute/20_documentation/_index.md @@ -1,8 +1,7 @@ --- -title: Documentation +title: Contributing Documentation url: /contribute/docs/ --- -# Contributing Documentation You are welcome to **contribute documentation** to Gardener. diff --git a/website/documentation/contribute/30_community/_index.md b/website/documentation/contribute/30_community/_index.md deleted file mode 100644 index ead9fe4c..00000000 --- a/website/documentation/contribute/30_community/_index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Community -#description: -sidebar: true -menu: sln -weight: 50 ---- -# Community -If you would like to join the growing Gardener community, here are the places where you can meet like-minded contributors. - -### Slack Channel - -[#gardener](https://kubernetes.slack.com/messages/gardener), sign up [here](http://slack.k8s.io/). - -### Mailing List - -[gardener@googlegroups.com](https://groups.google.com/forum/?fromgroups#!forum/gardener) - -The mailing list is hosted through Google Groups. To receive the lists' emails, [join](https://support.google.com/groups/answer/1067205) the group, as you would any other Google Group. - -### Twitter - -Follow [@GardenerProject](https://twitter.com/GardenerProject) on Twitter. Please mention @GardenerProject -in your own posts about Gardener. - -### Accessing community documents - -In order to foster real time collaboration there are working documents and notes that are taken in Google Docs, -and then transferred to this repository if appropriate. - -To gain edit access for these documents, you must subscribe to the -[gardener mailing list](https://groups.google.com/forum/?fromgroups#!forum/gardener), -as these documents are shared automatically with anyone who subscribes to that list. - -### Bi-Weekly Meetings - -We have a PUBLIC and RECORDED bi-weekly meeting. We meet every other Friday at [10:00 CET](https://www.google.de/search?q=10+CET+to+local+time) over Zoom. Find recordings in the [Gardener Youtube channel](https://www.youtube.com/channel/UCwUhwKFREV8Su0gwAJQX7tw/videos). Let us know if you want to participate and live in a timezone where 10:00 CET is in the night, we can also schedule meetings on Thursday [17:00 CET](https://www.google.de/search?q=17+CET+to+local+time). - -See the meeting calendar on the web at [calendar.google.com](https://calendar.google.com/calendar/embed?src=gardener.cloud.community%40gmail.com), or paste this [iCal url](https://calendar.google.com/calendar/ical/gardener.cloud.community%40gmail.com/public/basic.ics) into any iCal client. - -If you have a topic you'd like to present or would like to see discussed, please propose a specific date on the [Gardener Community Meeting Agenda](https://docs.google.com/document/d/1314v8ziVNQPjdBrWp-Y4BYrTDlv7dq2cWDFIa9SMaP4). Find minutes in the same document. Please upload slides or other documents you presented to the -[Gardener Community Meeting folder](https://drive.google.com/drive/u/0/folders/1myXFoaFL_9fYJdUwnZcIXMBpx3dynhM8). Subscribe to the [gardener mailing list](https://groups.google.com/forum/?fromgroups#!forum/gardener) to get edit permissions. \ No newline at end of file From 2b094fffddfcd25d82481fe4d580b53001112f98 Mon Sep 17 00:00:00 2001 From: Nikolay Boshnakov Date: Fri, 21 Oct 2022 17:59:00 +0300 Subject: [PATCH 2/2] Resolved comments --- website/community/_index.md | 2 +- .../contribute/20_documentation/10_organisation/_index.md | 2 +- .../20_documentation/40_style_guide/concept_template.md | 4 ++-- .../20_documentation/40_style_guide/reference_template.md | 8 ++++---- .../20_documentation/40_style_guide/task_template.md | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/website/community/_index.md b/website/community/_index.md index f64176cf..0a9e3b83 100644 --- a/website/community/_index.md +++ b/website/community/_index.md @@ -27,4 +27,4 @@ The recordings are published on the [Gardener Project YouTube channel](https://w ### Presenting a Topic -If there is a topic you would like to present, message us in our slack channel or get in touch with [Jessica Katz](mailto:jessica.katz@sap.com). \ No newline at end of file +If there is a topic you would like to present, message us in our [#gardener](https://kubernetes.slack.com/messages/gardener) slack channel or get in touch with [Jessica Katz](mailto:jessica.katz@sap.com). \ No newline at end of file diff --git a/website/documentation/contribute/20_documentation/10_organisation/_index.md b/website/documentation/contribute/20_documentation/10_organisation/_index.md index 96500335..a47c94a3 100644 --- a/website/documentation/contribute/20_documentation/10_organisation/_index.md +++ b/website/documentation/contribute/20_documentation/10_organisation/_index.md @@ -14,7 +14,7 @@ The Gardener project implements the *documentation-as-code* paradigm. Essentiall Documentation that can be affiliated to component is hosted and maintained in the component repository. -A template for organizing documentation sources is to place them all in a `docs` folder and organize it there per role activity. For example: +A good way to organize your documentation is to place it in a 'docs' folder and create separate subfolders per role activity. For example: ``` repositoryX diff --git a/website/documentation/contribute/20_documentation/40_style_guide/concept_template.md b/website/documentation/contribute/20_documentation/40_style_guide/concept_template.md index 18f23ea7..fe25648e 100644 --- a/website/documentation/contribute/20_documentation/40_style_guide/concept_template.md +++ b/website/documentation/contribute/20_documentation/40_style_guide/concept_template.md @@ -19,5 +19,5 @@ This adds additional information that belongs to the topic discussed in the pare This section gives the user all the information needed in order to understand the topic. ## Related Links -* [Link 1](./page.md) -* [Link 2](./page.md) +* [Link 1]() +* [Link 2]() diff --git a/website/documentation/contribute/20_documentation/40_style_guide/reference_template.md b/website/documentation/contribute/20_documentation/40_style_guide/reference_template.md index 5a2b0462..2a151368 100644 --- a/website/documentation/contribute/20_documentation/40_style_guide/reference_template.md +++ b/website/documentation/contribute/20_documentation/40_style_guide/reference_template.md @@ -11,9 +11,9 @@ This section gives the user all the information needed in order to understand th | Content Type | Definition | Example| |:----|:-----|:-----| -| Name 1 | Definition of Name 1 | [Relevant link](./page.md) | -| Name 2 | Definition of Name 2 | [Relevant link](./page.md) | +| Name 1 | Definition of Name 1 | [Relevant link]() | +| Name 2 | Definition of Name 2 | [Relevant link]() | ## Related Links -* [Link 1](./page.md) -* [Link 2](./page.md) +* [Link 1]() +* [Link 2]() diff --git a/website/documentation/contribute/20_documentation/40_style_guide/task_template.md b/website/documentation/contribute/20_documentation/40_style_guide/task_template.md index dfe1cfaf..9dfe4736 100644 --- a/website/documentation/contribute/20_documentation/40_style_guide/task_template.md +++ b/website/documentation/contribute/20_documentation/40_style_guide/task_template.md @@ -28,5 +28,5 @@ Screenshot of the final status once all the steps have been completed. ## Related Links Provide links to other relevant topics, if applicable. Once someone has completed these steps, what might they want to do next? -* [Link 1](./task_template.md) -* [Link 2](./task_template.md) +* [Link 1]() +* [Link 2]()