Skip to content

Document Basic Guide

This guide provides basic recommendations for your documents.

Framework

There are tons of static site generators and themes out there and choosing the right one for your tech stack is a tough decision.

Use markdown to write your articles - [Mandatory]

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. GitHub + markdown is a best practice of Documentation as Code.

💡 Comparing with rich text based Cisco wiki, markdown documents are easier to maintain, closer to project, highly customizable, friently for process tracking. Let's write document in Developer Way.

Use GitHub Pages to host your wiki site - [Reference]

GitHub Pages is hosted directly from GitHub repository, all changes will be dynamicly reflected to the site, it can save you lots of work for building and deploying your document project.

💡 Here are some examples around us:

Use Jekyll to serve your wiki site - [Reference]

There are tons of static site generators and themes out there and choosing the right one for your tech stack is a tough decision. Jekyll has the advantage that natively supported by GitHub Pages.

💡 Click the GitHub icon on the up right corner, then fork and clone this project to start your adventure with Jekyll now!

💡 You can still use other static site generators like Hugo, Hexo, VuePress... but strongly recommend to use the same framework among Monitoring & Alerting team.

Process

Review and approval is needed before a document can be merged - [Mandatory]

Make document as part of our development life cycle.

Evaluate document effort on planning meeting - [Mandatory]

If there is document work (add or update), we should know and plan for it on our planning meeting.

If there is document change, make it as part of your sprint story and assign a proper point.

💡 Generally, big feature, design feature, and research should have documents. Other functions need to consider whether there are existing documents that need to be updated.

Link README.md to correct wiki page - [Recommend]

Make good use of README.md, especially for those big features. Theoretically a project must have at least one README.md to guide user to related wiki page.