Project

General

Profile

Actions

User story #7686

closed

Improve documentation organization and add missing sections

Added by Alexis Mousset over 8 years ago. Updated about 6 years ago.

Status:
Rejected
Priority:
N/A
Assignee:
-
Category:
Documentation
UX impact:
Suggestion strength:
User visibility:
Effort required:
Name check:
Fix check:
Regression:

Description

Clean foswiki.

It still contains outdated content like http://www.rudder-project.org/foswiki/Download/WebHome which is the second Google result for "Download Rudder".

Could be the first page of the manual.

Add a getting started section

At the very beginning of the manual. It should follow a simple scenario from the beginning to the end (like a web platform installation), to help discover Rudder workflow.

  • Installation of a demo platform ("getting started" on normation.com)
  • Basic node management, quick explanation of the concepts
  • Create directives (built-in+technique editor, with file copy, templating), rules, quick explanation of the concepts.
  • Basic agent commands
  • etc.
  • This chapter should include a lot of screenshots and tips.

We should probably initially target this section to 3.1.

Split the "Introduction" chapter

  • Move things to the Reference chapter (dependency graph, list of Rudder packages)
  • Replace texts by schema and diagrams
  • Move to "Requirements" part into the Installation chapter

Split the "Advanced usage" chapter

  • Move all administration elements (multi server, relays) into "Administration"
  • Rename it "Advanced Configuration Management" (with technique creation)

Integrate the "Handbook" into Administration

Add "Troubleshooting" and "Known issues" sections

  • Integrate the relevant content from the FAQ
  • troubleshooting workflow (rudder server debug, relevant logfiles, etc.)
  • known issues like limitations of ncf reporting, etc.

Have a better indexing policy

For now the first result in Google is the 2.3 doc, we should probably only have one indexable version.

Add a section in administration about integration with other tools

  • monitoring Rudder
    • document log files to check for errors
    • the format of non-compliance-reports.log
    • hexample of compliance API
    • give an example of logstash grok for non-compliance
    • rudder agent health on 3.3.
  • how to use the API to integrate with Rundeck, Ansible, etc.

Subtasks 13 (0 open13 closed)

User story #7701: Replace the one page doc with a webhelp-based versionRejectedAlexis Mousset2015-12-29Actions
User story #7707: Reorganize the documentation contentRejectedAlexis Mousset2015-12-30Actions
User story #7708: Improve appearance of the webhelp docReleasedJonathan CLARKE2016-02-08Actions
User story #7885: Change 3.2 packaging to use the localsearch version of the webhelp docReleasedJonathan CLARKE2016-02-08Actions
User story #7886: Improve appearance of the webhelp doc - changes for 3.0ReleasedJonathan CLARKE2016-02-08Actions
User story #7887: Improve appearance of the webhelp doc - changes for 3.1ReleasedJonathan CLARKE2016-02-08Actions
User story #7888: Improve appearance of the webhelp doc - changes for 3.2ReleasedJonathan CLARKE2016-02-08Actions
User story #7904: Improve appearance of the webhelp doc - changes for 3.3RejectedAlexis Mousset2016-02-11Actions
Bug #7905: Broken API doc linkReleasedJonathan CLARKE2016-02-11Actions
User story #7729: Add a section in administration about integration with other toolsReleasedJonathan CLARKE2016-01-06Actions
User story #7731: Add a section in administration about integration with other tools for 3.1ReleasedJonathan CLARKE2016-01-06Actions
User story #7808: Add a section in administration about integration with other tools for 3.2ReleasedJonathan CLARKE2016-01-19Actions
User story #7732: Add a "known issues" sectionRejectedAlexis Mousset2016-01-06Actions

Related issues 3 (0 open3 closed)

Related to Rudder - User story #7709: Integrate a DocSearch field in the public documentationRejected2015-12-31Actions
Related to Rudder - User story #7688: Add a getting started section in the manualRejectedAlexis MoussetActions
Is duplicate of Rudder - User story #7121: Possible improvements for the webhelp docRejected2015-08-20Actions
Actions #1

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #2

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #3

Updated by Alexis Mousset about 8 years ago

  • Related to User story #7709: Integrate a DocSearch field in the public documentation added
Actions #4

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #5

Updated by Alexis Mousset about 8 years ago

  • Is duplicate of User story #7121: Possible improvements for the webhelp doc added
Actions #6

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #7

Updated by Alexis Mousset about 8 years ago

  • Related to Bug #6220: Document /var/log/rudder/compliance/non-compliant-reports.log added
Actions #8

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #9

Updated by Alexis Mousset about 8 years ago

  • Related to deleted (Bug #6220: Document /var/log/rudder/compliance/non-compliant-reports.log)
Actions #10

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #11

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #12

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #13

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #14

Updated by Alexis Mousset about 8 years ago

  • Description updated (diff)
Actions #15

Updated by Alexis Mousset almost 8 years ago

  • Description updated (diff)
Actions #16

Updated by Alexis Mousset about 6 years ago

  • Description updated (diff)
Actions #17

Updated by Alexis Mousset about 6 years ago

  • Description updated (diff)
Actions #18

Updated by Alexis Mousset about 6 years ago

  • Related to User story #7688: Add a getting started section in the manual added
Actions #19

Updated by Alexis Mousset about 6 years ago

  • Status changed from New to Rejected

Closing as the only missing part is the getting started which is #7688

Actions

Also available in: Atom PDF