Create top-notch GitHub wiki documentation

[mosherubin]

The Goal

Prepare top-notch, visually appealing GitHub wiki documentation for NsiqCppStyle. The documentation should be as clear, simple, and appealing as possible, and should provide everything an NsiqCppStyle user needs to write style rules.

Most GitHub projects either have no wiki-based documentation, or the documentation is of poor quality. The goal is to make NsiqCppStyle attractive to potential users by providing world-class documentation.

It will take time and patience to implement this issue, given the wealth of technical information within the project. We should plan the wiki page structure before diving in. This page should serve as the whiteboard for developing the best page structure. Once decided, it will be easier to tackle the wiki pages one at a time.

Resources / References

List of excellent GitHub wiki examples

Following is a short list of GitHub projects that have attractive and high-quality wiki documentation (by all means, if you find a great example, add it to the list!). We should feel free to emulate the best of what there is out there.

• Netflix/Hystrix : Excellent example of what one can do with the GitHub wiki
• snowplow/snowplow
  • The project links to non-wiki documentation, but the topics listed there can be helpful for NsiqCppStyle
• d3/d3 : Look at the list of wiki pages for ideas

How to view a wiki's raw markdown

To see the raw markdown of a wiki page you like, slightly manipulate the project wiki page URL to generate the desired URL. Note that the URL is case-sensitive. Here are two examples to show how.

Example 1: View raw markdown for the wiki home page of Netflix/Hystrix

The URL to the GitHub wiki home page of the Netflix/Hystrix project is https://github.com/Netflix/Hystrix/wiki. Looking at that page shows the page title is "Home":

• Begin with the following domain: https://raw.githubusercontent.com/wiki/
• Append the project repository's name: https://raw.githubusercontent.com/wiki/Netflix/Hysterix/
• Append the page title: https://raw.githubusercontent.com/wiki/Netflix/Hysterix/Home
• Append .md: https://raw.githubusercontent.com/wiki/Netflix/Hysterix/Home.md

Example 2: View raw markdown of d3/d3's Tutorials wiki page

The URL to the GitHub wiki home page of the Netflix/Hystrix project is https://github.com/d3/d3/wiki. Looking at that page shows the page title is "Tutorials":

• Begin with the following domain: https://raw.githubusercontent.com/wiki/
• Append the project repository's name: https://raw.githubusercontent.com/wiki/d3/d3/
• Append the page title: https://raw.githubusercontent.com/wiki/d3/d3/Tutorials
• Append .md: https://raw.githubusercontent.com/wiki/d3/d3/Tutorials.md

Action Items

• Create a brainstormed list of topics the wiki should deal with
• Structure the list of topics into a well-ordered hierarchy
• Develop an NsiqCppStyle logo for the project and wiki pages
• The project's README.md file can reference wiki pages
• Be sure to include pages to pique readers' interests, for example:
  • Step-by-step tutorials
  • HOW-TO
  • FAQ
  • Case studies
  • History-related (e.g., how did NsiqCppStyle come about)
  • Product comparison pages (e.g., NsiqCppStyle vs. Clang-Tidy)

[kunaltyagi]

@mosherubin Thanks for this. I somehow didn't see updates from this in my notifications. I've updated my notification settings, so I should be more prompt now. Apologies for any headaches and issues I might have caused along the way