Project Design: Help Files Template
“It doesn’t matter how good your software is,
because if the documentation is not good enough,
people will not use it.”
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.
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 servein the terminal where the files are located.Customize this template by editing the files in the
docs/folder to meet your Project needsAdjust the navigation by editing the
mkdocs.ymlfile found in the root folder of the templateTo preview the changes in your document run
mkdocs buildand thenmkdocs servein 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 serveto see a preview andmkdocs gh-deployto publish your changes to your website.
Project Design: Help Files Template Example Site
References
