theYvonne

View Original

Project Design: Help Files Template

Yvonne Beirne FitzGerald

Why Create Project End User Documentation?

Project Design: Help Files Template Example Site

Creating amazing user documentation for a Project is critical to the project's success. With good user documentation, a tool becomes easier to use, increases the chance of mass adaption and citation, reduces the support burden for the developer, creates raving fans, and increases the professional feel of the project. All these benefits can lead to increase funding and opportunities for the developers and happy users. Good user documentation also leads to better code that is easier to maintain. Unfortunately, user documentation is one part of a project that many developers skip or ignore, leaving their users to struggle to implement the new Tool/App completely—creating lost opportunities for both the end user and the developers.

Project Design: Help Files Template Example Site

Developing excellent user documentation for a Project/Tool/App is streamlined using this predefined Template. This Template walks one through the process of creating fantastic user documentation one page at a time. The pages in the Template cover a specific topic of user documentation, formating options, notes, and points to ponder. The Template then quickly converts to a website using MkDocs. Or you can use this Template as guidance for your own approach. Not every page or suggestion needs to be implemented; it is highly encouraged that Getting Started, How To Guide, and Reference Guide pages are included.

Template Repository In GitHub

GitHub enables defining a repository as a template. This feature allows users to create new repositories with the same directory structure, branches, and files. Template repositories enable a standard format for projects within a group or organization or define a typical setup for your work.

What Is MkDocs

MkDocs is an easy-to-use static HTML site generator that enables the creation of Project Documentation for end users quickly. It is easy to customize the project documentation as well as the look and feel of the site. The documentation source files use Markdown to format the documentation pages. Configuration of the site uses a YAML configuration file. These combined processes enable the previewing of the site as you work. In addition, it comes with a built-in site search function, allowing the end user to find information faster. Sites built using MkDocs can be hosted anywhere, including GitHub pages and Amazon S3.

How To Use This Repository

  • Go to https://github.com/YvonneBeirneFitzGerald/Project-Design-Help-Files-Template

  • Click the 'Use This Template' button on the right (Note: sometimes this button is colored green)

  • Name your copy of the Template a name related to your Tool/App

  • Go to your computer's command line

    • Clone the new repository locally. Additional info from GitHub on how to do it.

    • Goto to the root of the template on your computer

    • Install MkDoc following their Instructions

    • To see a preview of your documents run mkdocs serve in the terminal where the files are located.

    • Customize this template by editing the files in the docs/ folder to meet your Project needs

    • Adjust the navigation by editing the mkdocs.yml file found in the root folder of the template

    • To preview the changes in your document run mkdocs build and then mkdocs serve in the terminal

  • Ready To Publish and Create Documentation Website

    • In the terminal, run mkdocs gh-deploy (Additional Information from MkDocs), it will return the web address of your new site.

    • Visit the address to check out the results

    • Add links in your Project to link to the documentation

  • Updating Documentation

    • When editing documentation continue to use mkdocs serve to see a preview and mkdocs gh-deploy to publish your changes to your website.

Project Design: Help Files Template Example Site

References