##Documentation
GOAL: This exercise will help you document your projects, or guide you through some exercises that will help you think critically about the kinds of documentation you might need.
FORMAT: Markdown or text document
TIME TO COMPLETE: 30 mins - 1 hour.
TECHNOLOGY: Your favorite text editor or Markdown viewer. Record and share your findings in your GitHub repository.
INSTRUCTIONS
Choose a project, one that you've developed, or published, and consider the following bullets as you do a documentation audit of that project. Take notes on as you address these bullets in your makdown document, and save it to your folder. It's worth noting that we recommend you attempt documentation throughout your project, which makes publishing and versioning your project much easier in the long run, however often some of the polish that goes into documentation comes at the end of the project when you know what you've built and can articulate its idiosyncracies and current status accurately. This exercise is meant to help you polish your documentation practice pre-launch of a project.
- maybe reference your sustainability plan or challenge exercise from the Explore phase, if relevant
- list a few groups you might like to engage in your project or incorporate into the community that uses your project
- sort these people/groups into "Contributors" and "Users" lists
- draft a short message to your contributors or users summarizing your project in one sentence and defining the type of contribution you'd like to solicit from them
- this may develop into a more robust contributor.md file or a little website for your community but for now it can be a draft text document.
- draft some boilerplate documents that correspond to your project, which you can evolve over time
- License: guide here - instructions about how your project can be shared/reused
- Readme: guide here - brief details about your project, now to install/deploy/use it and what purpose it serves
- Code of Conduct: guide here - guide to welcome and unwelcome behavior
- Contributor file: guide here - how to contribute or participate in your project/community
- find an appropriate place to publish these documents and link them to your project -- they might just be footnotes on documentation associated with your work, or they might be a separate github repository of referenced standards for your project, or they might be on the website for your project.
- choose a place that's easily findable for your target audience
- review the resources referenced below for style guidelines and design patterns that can help you guide your documentation
- consider incorporating screenshots or useful examples that punctuate general documentation with some flavor and visual interest, as suggested in this guide to what not to do with docs
- consider also offering your docs in other (not only online) formats, as you can do with helpndoc and other free tools that offer multiple documentation exports
RESOURCES
- A beginners guide to writing documentation
- Best practices for open source contributions
- 18F Open Source Style Guide | sample guide
- Open Stack guide to maintaining and evolving docs
- Daux.io - a documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly.
- Document - Bootstrap - a boilerplate project that incorporates JavaScript libraries, jQuery plugins, and Twitter Bootstrap to save developers time when creating project pages and providing users with custom project builds
- Docco - produces HTML that displays your comments alongside your code. Comments are passed through Markdown, and code is passed through Pygments syntax highlighting.
- Tocify - a jQuery plugin that dynamically generates a table of contents (TOC). Tocify can be optionally styled with Twitter Bootstrap or jQueryUI Themeroller, and optionally animated with jQuery show/hide effects