Home
Welcome to the wiki-docs wiki!
The above is the default starting content when you use the "wiki" feature in
GitHub.
It lives in your Home.md page.
Firstly, a wiki in GitHub is for developers, architects, business analysts, and other tech-minded folks. Not everyone is comfortable with GitHub. A GitHub wiki is best for technical documentation targeting appropriate readers. In open source, or proprietary technical projects, your "tech-minded business folks" are also consumers (direct or indirect) of your project.
Secondly, a GitHub wiki is not for business folks! These will prefer other document types and styles, such as documents (Word, GDocs), spreadsheets (Excel, GSheets), presentations (PowerPoint, GSlides), and sketch boards (Mural and ilk). In open source projects, this is less of a concern, and target audiences are usually technically savvy.
Tip
You may find it helpful to view your wiki pages locally while you edit them (if preferring local editors to the GitHub UI editor). If so, tools are available to you. My choices include:
- IntelliJ — Good editing tools and views wiki diagrams out of the box.
- VSCode — Good editing tools and with extensions supports viewing wiki diagrams.
- Command line — A good viewing tool is
mdvbut without support for wiki diagrams. It depends onpandocand the command-line browser of your choice (lynxby default).
- Any open source project with code in GitHub
- Documentation outside your source code such as your APIs
- Diagrams: for sharing with developers, architects, business, and others
- Capture of discussions such as ADRs (architecture decision records)
- Keeping documentation under source control, just like your program code
- Most importantly, let anyone—developers or others—edit documentation easily, and in plain language text
- Storing proprietary documents; use links in the wiki for references to external documents. You can store these in the GitHub wiki repository, but it may not fit your needs
- Complex diagrams relying on special features of particular tools. Mermaid (out-of-the-box with GitHub wikis) is an excellent tool, but may not have the feature set you want
- Large wikis with many pages needing organization: a GitHub wiki is a flat page structure (see GitHub discussion). Organizing structure is through the Navigation sidebar
- Documentation access for business users unfamiliar with GitHub
If your GitHub project does not yet have a wiki, go to the "Wiki" option in the GitHub UI for your project (it appears midway in the top navigation bar) and create the default "Home" page. If you do not see the "Wiki" option, you may need a project owner or administrator to enable the option in "Settings | General":
For more details on GitHub wikis, see Documenting your project with wikis. After your wiki is ready, see Working with the GitHub wiki or look at Sample wiki pages below.
A good resource for getting started or exploring wiki features available to you is Getting started with writing and formatting on GitHub.
For documenting your REST endpoints and JSON content, start with these two pages, and then rename/edit:
- Template REST API — document your REST endpoints
- Template JSON Models — document your JSON payloads
- Template Constants — document your manifest constants
You will rename these to remove the "Template" prefixes, and can provide your readers with "REST API" and "JSON Models" wiki documentation pages.
Note
You may want to update your "Sidebar" (right-hand side in the GitHub wiki
UI) to highlight these and other pages.
The example _Sidebar.md talks about this.
- Examples of diagramming — take advantage of Mermaid in your documentation
Note
The [[some page title]] syntax uses GitHub markdown features.
In vanilla Markdown the page links are:
This work is in the Public Domain.
This is an example of using a common footer across your wiki pages.