├── README.adoc ├── infrastructure-goals-planning.adoc └── templates ├── readme-template.adoc ├── release-notes-template.adoc ├── tutorial-template.adoc └── user-manual-template.adoc /README.adoc: -------------------------------------------------------------------------------- 1 | = Asciidoctor Documentation 2 | ifdef::env-github[] 3 | :warning-caption: :warning: 4 | endif::[] 5 | :infra-ref: https://github.com/asciidoctor/asciidoctor-documentation/blob/master/infrastructure-goals-planning.adoc 6 | :templates-ref: https://github.com/asciidoctor/asciidoctor-documentation/tree/master/templates 7 | :readme-repo: https://github.com/asciidoctor/asciidoctor-documentation/blob/master/README.adoc 8 | :issue-docs: https://github.com/asciidoctor/asciidoctor-documentation/issues?state=open 9 | :homepage: http://asciidoctor.org 10 | :sources: https://github.com/asciidoctor/asciidoctor 11 | :issues: https://github.com/asciidoctor/asciidoctor/issues 12 | :forum: http://discuss.asciidoctor.org 13 | :org: https://github.com/asciidoctor 14 | 15 | WARNING: *This repository has been archived.* 16 | If you'd like to contribute to the documentation, see the https://github.com/asciidoctor/docs.asciidoctor.org[docs.asciidoctor.org repository]. 17 | 18 | *The information and processes in this README are being brainstormed and discussed. 19 | They have not been implemented!* 20 | 21 | But speaking of brainstorming, we're looking for people to add some *thunder and lightning*! 22 | 23 | Do you have ideas about how to: 24 | 25 | * automate documentation so code and references stay up-to-date? 26 | * flag and tag documents according to versions? 27 | * link source code to documents across repositories? 28 | * outline and structure user-friendly manuals? 29 | * write, edit, automate, deploy, etc. documentation? 30 | 31 | If so, don't hesitate to file an issue, start a wikipage, fork this repo, or join the discussion *link pending* on the mailing list. 32 | 33 | == Overview 34 | 35 | The Asciidoctor Documentation project's goal is to build, store, and distribute the content relevant to the Asciidoctor organization and its projects. 36 | 37 | This repository will store and maintain the: 38 | 39 | * General documentation guidelines 40 | * General document building instructions 41 | * Asciidoctor Organization documents (such as the {infra-ref}[Infrastructure Goals and Planning] document) 42 | * {templates-ref}[Content guides and templates] for writing READMEs, changelogs, manuals, tutorials, etc. 43 | * Source code for building documents that include content from multiple repositories 44 | * Writer's guide 45 | * General contributor manual 46 | * General developer guidelines 47 | * FAQ 48 | * Tutorials (which will be released to the website) 49 | * Additional learning materials (presentations, etc.) that are cross-repository 50 | * Project collateral 51 | 52 | Additionally, the Asciidoctor Documentation repository will distribute each project's documentation for publication on the Asciidoctor website. 53 | It will build additional and alternate forms of documentation from content and code flagged and included throughout the repositories. 54 | 55 | == Asciidoctor Documentation repository structure 56 | 57 | The `asciidoctor-documentation` directory contains: 58 | 59 | * {readme-repo}[README] 60 | * {infra-ref}[Infrastructure Goals and Planning] 61 | * {templates-ref}[`/templates` directory] 62 | ** {templates-ref}/readme-template.adoc[README guide and template] 63 | ** {templates-ref}/release-notes-template.adoc[Release Notes guide and template] 64 | ** {templates-ref}/tutorial-template.adoc[Tutorial guide and template] 65 | ** {templates-ref}/user-manual-template.adoc[User Manual guide and template] 66 | 67 | [horizontal] 68 | README:: Purpose and description of the Asciidoctor Documentation project 69 | 70 | Infrastructure Goals and Planning:: Planning document outlining information, suggestions, and questions about building the Asciidoctor organization's infrastructure. 71 | 72 | Templates directory:: Location of the content guides and templates for writing READMEs, changelogs, manuals, tutorials, etc. 73 | 74 | README guide and template:: Style and structure suggestions for a project's README. 75 | 76 | Release notes guide and template:: Style and structure suggestions for a project's release notes. 77 | 78 | Tutorial guide and template:: Style and structure suggestions for a project's tutorials. 79 | 80 | User manual guide and template:: Style and structure suggestions for a project's user manual. 81 | 82 | NOTE: Many more guides and templates are planned, checkout the ideas and requests filed in the {issue-docs}[issue tracker] for more information. 83 | 84 | == Documentation for Asciidoctor core and other Asciidoctor organization projects 85 | 86 | Each project within the Asciidoctor organization and Asciidoctor core will store and maintain its own: 87 | 88 | * Installation and usage quick start 89 | * User manual 90 | * Technical manual 91 | * Syntax and code dictionary 92 | * README 93 | * Changelog 94 | * License 95 | * Specific contribution instructions 96 | 97 | The core repository will also store and maintain the: 98 | 99 | * Syntax writing quick start 100 | 101 | == Contributing instructions 102 | 103 | Pending 104 | 105 | === Issues 106 | 107 | Use this repository's issue tracker to file issues and feature requests regarding the goals of this repository and its documents. 108 | 109 | == Build instructions 110 | 111 | See {infra-ref}[Infrastructure Goals and Planning] for more information. 112 | 113 | // == Copyright and licensing information 114 | 115 | // == Author(s) 116 | 117 | // == Thanks, acknowledgments, and credits 118 | 119 | == General Asciidoctor Contact and help information 120 | 121 | Project home page:: {homepage} 122 | 123 | Core source code repository:: {sources} 124 | 125 | Core issue tracker:: {issues} 126 | 127 | Mailing list / forum:: {forum} 128 | 129 | GitHub organization:: {org} 130 | 131 | //// 132 | == Bugs 133 | 134 | * List of known bugs 135 | * Instructions on reporting new bugs 136 | 137 | == Changelog 138 | //// 139 | 140 | 141 | 142 | 143 | -------------------------------------------------------------------------------- /infrastructure-goals-planning.adoc: -------------------------------------------------------------------------------- 1 | = Infrastructure Goals and Planning 2 | Sarah White 3 | :rubygem-ref: http://guides.rubygems.org/make-your-own-gem/ 4 | :templates-ref: https://github.com/asciidoctor/asciidoctor-documentation/tree/master/templates 5 | :docs-ref: https://github.com/asciidoctor/asciidoctor-documentation 6 | :rpm-ref: https://github.com/asciidoctor/rubygem-asciidoctor-rpm 7 | :website-ref: https://github.com/asciidoctor/asciidoctor.org 8 | :config-ref: https://github.com/infinispan/infinispan.github.io/blob/develop/_config/ispn.yml 9 | :fetch-ref: https://github.com/infinispan/infinispan.github.io/blob/develop/bin/fetch_docs.rb 10 | :publish-ref: https://github.com/infinispan/infinispan.github.io/blob/develop/bin/publish_production.sh 11 | :infinispan-web-repo: https://github.com/infinispan/infinispan.github.io 12 | 13 | The Asciidoctor Organization is an incredibly creative community, and we want it to continue to innovate and expand. 14 | A project's infrastructure can support or hinder a community. 15 | For this reason, we would like to implement an organizational infrastructure that is focused on the following goals: 16 | 17 | * Making contributing to and using the Asciidoctor project and modules unambiguous and fun 18 | * Writing and distributing accurate and complete documentation 19 | * Testing everything 20 | * Automating tests, builds, release processes, documentation, and anything else we can possibly think of! 21 | 22 | The infrastructure should not burden the Asciidoctor contributors while it streamlines the delivery of up-to-date resources to the Asciidoctor users. 23 | 24 | To build such an infrastructure requires input and feedback from the contributors and some iteration trial and error. 25 | 26 | Dan and I have put together information, suggestions and questions on topics ranging from <> to <> to get this infrastructure conversation party started. 27 | 28 | == Release Numbering 29 | 30 | Release numbers can consist of a major, minor, and micro number. 31 | 32 | The next major release of Asciidoctor Core will be 1.5.0. 33 | 34 | Major number changes indicate numerous new features and possible infrastructure and architecture changes to the software. 35 | 36 | . Must major releases be backward or forward compatible? 37 | . Must they be backward or forward compatible with the current major release of Asciidoctor Core and the modules? 38 | 39 | Minor numbers indicate a few new features. 40 | 41 | . Would minor numbers also include bug fixes? 42 | . Could they include incompatible changes? 43 | . Must they be backward or forward compatible? 44 | . Must they be backward or forward compatible with the current major release of Asciidoctor Core and the modules? 45 | 46 | Micro numbers are backward or forward compatible and contain bug fixes and patches. 47 | 48 | . Would micro number releases also include new features? 49 | . Must they be backward or forward compatible with the current major release of Asciidoctor Core and the modules? 50 | 51 | === Compatibility 52 | 53 | . How do we define backward and forward compatible for Asciidoctor Core and for the modules? 54 | 55 | == Release Candidates 56 | 57 | Asciidoctor Core has issued release candidates (RC) in the past. 58 | 59 | If we continue this practice the next major release candidate of Asciidoctor Core will be 1.5.0.rc1. 60 | 61 | . Is this a practice we want to continue? 62 | . If so, what would be the criteria, workflow and timeline for creating and cutting a release candidate? 63 | . Would the modules also cut release candidates? 64 | 65 | == Release Branches 66 | 67 | In order to maintain stable snapshots of the release versions and their associated documentation, the major number releases should be branched off of the master code base. 68 | 69 | The next Asciidoctor Core release branch would be named 1.5.X. 70 | The X is used to name the branch because all micro number releases for 1.5 will also occur on this branch. 71 | 72 | When 1.5.0 is ready for release, a snapshot of the 1.5.X branch is tagged as 1.5.0. 73 | Subsequent micro releases are created and tagged on the same branch. 74 | 75 | Minor number releases are branched from master, not from other release branches. 76 | 77 | This workflow allows for new features destined for the next minor or major release to be developed while bug fixes are applied and deployed to the current and past releases. 78 | 79 | == Release Criteria 80 | 81 | . How will we plan releases? 82 | . How will we determine when a release should be tagged? 83 | 84 | A release can be tagged when the following items have been completed: 85 | 86 | * Branch code tested per release number requirements (i.e. micro number release is backward and forward compatible with Core and/or modules). 87 | * README updated 88 | * Changelog generated 89 | * User Manual updated to reflect changes and/or new features 90 | * Technical Manual updated to reflect changes and/or new features 91 | * RDoc (or applicable API documentation) generated 92 | * Release announcement drafted and staged for publication on the website (this may not apply to all releases) 93 | 94 | The <> expands on creating, updating and automating the documents listed above. 95 | Content guides for the documents listed above are under discussion and development in the {templates-ref}[Documentation repository]. 96 | 97 | === Testing criteria 98 | 99 | . What are the testing requirements for Asciidoctor Core and the modules? 100 | . Who is responsible for testing? 101 | 102 | == Releasing the Rubygem 103 | 104 | . Are the directions for creating the rubygem documented? 105 | . Does this process need to be modified or streamlined? 106 | . Are their other organization repositories we would like to release as a rubygem? 107 | . If so, how would we coordinate or integrate them with the Core rubygem? 108 | 109 | The Asciidoctor Core rubygem contains the source code, README, Changelog, and License. 110 | 111 | Reference: RubyGems Guide:{rubygem-ref}[Make your own gem] 112 | 113 | === Packaging the rubygem 114 | 115 | Once the rubygem has been published, it is subsequently packaged for Fedora and Debian. 116 | The build materials and instructions for packaging the Fedora RPM are hosted in the {rpm-ref}[RPM repository]. 117 | 118 | . Does this process need to be modified or streamlined? 119 | . Are there other modules we would like to package? 120 | . If so, how would we coordinate or integrate that with the Core rubygem package? 121 | 122 | Additionally, are there any extra steps we want to take (if applicable) to ease installation on Windows or Mac? 123 | 124 | == Documentation 125 | 126 | Like code, documentation should only be written in one place. 127 | This improves accuracy and maintainability. 128 | 129 | Therefore, the current documentation, which is stored in the {website-ref}[Asciidoctor website repository] will be transferred to its related code repository. 130 | 131 | Each project and Asciidoctor Core will store and maintain its own: 132 | 133 | * Installation and usage quick start 134 | * User manual 135 | * Technical manual 136 | * Syntax and code dictionary 137 | * README 138 | * Changelog 139 | * License 140 | * Specific contribution instructions 141 | 142 | The Core repository will also store and maintain the: 143 | 144 | * Syntax writing quick start 145 | 146 | We also want to publish the same content via a variety of channels. 147 | 148 | For example, the directions for installing Asciidoctor Core should be written in one source document, but then published in the README, User Manual, Installation Quick Start, blog posts, etc. 149 | 150 | And we want to create content that uses documentation from several repositories. 151 | 152 | For example, the Asciidoctor User Manual will include documentation from every module and Asciidoctor Core. 153 | 154 | To facilitate the cross-repository building of documentation and its distribution, we set up the {docs-ref}[Asciidoctor Documentation repository]. 155 | 156 | The Asciidoctor Documentation repository will distribute each project's documentation for publication on the Asciidoctor website. 157 | It will build additional and alternate forms of documentation from content and code flagged and included throughout the repositories. 158 | 159 | The Documentation repository will maintain the: 160 | 161 | * General documentation guidelines 162 | * General document building instructions 163 | * Asciidoctor Organization documents (such as this planning document) 164 | * {templates-ref}[Content guides and templates] for writing READMEs, changelogs, manuals, tutorials, etc. 165 | * Source code for building documents that include documentation from multiple repositories 166 | * Writer's guide 167 | * General contributor manual 168 | * General developer guidelines 169 | * FAQ 170 | * Tutorials (which will be released to the website) 171 | * Additional learning materials (presentations, etc.) that are cross-repository 172 | * Project collateral 173 | 174 | === Automation workflow 175 | 176 | The documentation directory structure within each repository should be somewhat consistent in order to automate the building of the distributed documentation. 177 | 178 | A repository's documentation will be stored in a top level file named `docs`. 179 | Any screenshots, images, figures, etc. for the documentation will be stored in `docs\assets\`. 180 | 181 | . Is this directory structure applicable to Gemfiles and the Java repositories? 182 | 183 | In order to improve the timeliness and accuracy of code snippets and examples included in the documentation: 184 | 185 | * Code snippets and examples should be linked and extracted from the source code or test cases so that the documentation is updated when the code is updated. 186 | * The example code must be tested. 187 | // 188 | 189 | . How will we flag source code for inclusion? 190 | . How will we test the code included in the documentation? 191 | . How will the documentation know when source code has changed and the document needs to rebuild? 192 | 193 | In order to build the documentation for the website, we can create scripts similar to the Infinispan project's. 194 | 195 | These scripts are stored in the {infinispan-web-repo}[Infinispan website repository]: 196 | 197 | * Configuration script dictating what to publish: {config-ref}[ispn.yml] 198 | * Script for retrieving the documentation from the repositories: {fetch-ref}[fetch_docs.rb] 199 | * Script to publish the documentation and website: {publish-ref}[publish_production.sh] 200 | 201 | == Issues 202 | 203 | Wording issues and commits to make generating the changelog as painless as possible... 204 | 205 | == Code comments 206 | 207 | Wording comments in the code to create great technical documentation... 208 | 209 | == Next steps 210 | 211 | Feed me, Seymour! 212 | 213 | 214 | 215 | 216 | -------------------------------------------------------------------------------- /templates/readme-template.adoc: -------------------------------------------------------------------------------- 1 | = README Template 2 | Sarah White 3 | 4 | CAUTION: This template is not finalized! It is a working draft, and it would love your input! 5 | 6 | The README is the minimum amount of documentation that is packaged with a gem or project. 7 | It is also part of the project's landing page on GitHub. 8 | 9 | *Audience* 10 | 11 | All levels of users and developers 12 | 13 | *Writing style* 14 | 15 | The README should be concisely written. 16 | However, it should be compelling and informative, as it will be the first document describing what your project does that many potential users will see. 17 | 18 | * Make sure to define terms and acronyms. 19 | 20 | .README Template 21 | ---- 22 | == Overview 23 | 24 | * Brief description of the project's purpose and main benefit(s) 25 | * The types of users this project helps 26 | * Link(s) to other primary help documents and resources 27 | 28 | == Operating systems and/or platforms it runs on 29 | 30 | Be brief, provide links to more detailed documentation 31 | 32 | == Dependency and configuration requirements 33 | 34 | Be brief, provide links to more detailed documentation 35 | 36 | == List of files/directory structure 37 | 38 | Optional depending on the complexity of the project 39 | 40 | == Basic installation instructions 41 | 42 | Be brief, provide links to more detailed documentation 43 | 44 | == Basic usage instructions 45 | 46 | Be brief, provide links to more detailed documentation 47 | 48 | == Copyright and licensing information 49 | 50 | == Author(s) 51 | 52 | == Thanks, acknowledgements, and credits 53 | 54 | == Basic contact and help information 55 | 56 | Provide links 57 | 58 | == Bugs 59 | 60 | * List of known bugs 61 | * Instructions on reporting new bugs 62 | 63 | == Changelog 64 | 65 | == Basic contributing instructions 66 | ---- 67 | -------------------------------------------------------------------------------- /templates/release-notes-template.adoc: -------------------------------------------------------------------------------- 1 | = Release Notes Guide and Template 2 | Sarah White 3 | :toc2: 4 | :icons: 5 | :idprefix: 6 | :idseparator: - 7 | :sectanchors: 8 | :source-highlighter: highlight.js 9 | 10 | [Warning] 11 | ==== 12 | * Need to confirm that template is adequately covered by the MIT license or if a CC license should also be applied. 13 | * Need links to examples once the release notes for 0.1.4 are completed. 14 | * Need an upgrade guide. 15 | * Need to choose between New and Noteworthy or Highlights or What's New 16 | * Need to choose between Additional Features and Changes or Minor Features and Changes or Other Features and Changes 17 | ==== 18 | 19 | This guide provides an outline, writing style guidelines and a document template to help you structure and write your release notes. 20 | It is not a set of rules. 21 | After you fork this document or copy the example template found below, feel free to remove or modify sections and syntax that aren't applicable to the release. 22 | 23 | == Release Notes Audience 24 | 25 | Asciidoctor users and developers 26 | 27 | == Writing and style guidelines 28 | 29 | *Header* 30 | 31 | Include and display: 32 | 33 | * title with release version number 34 | * version release date 35 | * table of contents 36 | 37 | *Preamble* 38 | 39 | In a few paragraphs, introduce the enhancements and changes that provide the most influential benefits or affect the majority of the user base. 40 | Then, in general terms, explain the benefit each enhancement/change has for the users. 41 | This is not where you describe technical specifics (code examples). 42 | 43 | Think overall themes, for example: 44 | 45 | * This release is for all the users who have been waiting for a DocBook 5 backend. 46 | * We've sped up the processor by three minutes! 47 | * Asciidoctor now interfaces with all your applicances. 48 | 49 | *Installation and Upgrade Notes* 50 | 51 | This section should be brief and link to other documents for users requiring more information. 52 | If there are no release-specific installation or upgrade changes, simply provide the links to the general installation and upgrade guides. 53 | 54 | Include information about: 55 | 56 | * user or developer environment changes 57 | * installation/compilation method changes 58 | * links to installation guide, upgrade guide, and sourcecode repository 59 | 60 | *New and Noteworthy/Highlights/What's New* 61 | 62 | This section is for specifically describing and providing code snippets for each enhancement or change that makes this release significant. 63 | 64 | *Features/Changes* 65 | 66 | Describe what this new enhancement or change does (its purpose/goal) and how it works. 67 | If it provides numerous features and/or results, they can be listed. 68 | 69 | When applicable, include: 70 | 71 | * attribute, option, syntax, etc. names and how/when they operate 72 | * example code 73 | * tips or caveats 74 | 75 | Also, provide links to related documentation or more information. 76 | 77 | *Additional Features and Changes/Minor Features and Changes/Other Features and Changes* 78 | 79 | Minor features and changes can be listed. 80 | Each list item includes a one sentence description with link to further documentation/information if applicable. 81 | 82 | *Changelog* 83 | 84 | The Changelog is an autogenerated, bulleted list that is included from a separate source file. 85 | Each list item states the issue number, linked to the issue tracker, and a one sentence description of the issue. 86 | 87 | *Deprecations* 88 | 89 | This section is structured the same way as the New and Noteworthy section. 90 | 91 | *Potential Breaking Changes* 92 | 93 | This section is structured the same way as the New and Noteworthy section. 94 | 95 | *Known Problems* 96 | 97 | This section is structured the same way as the Changelog section. 98 | 99 | == Template 100 | 101 | Copy the template below (between the set of dashes (+----+)) and paste it into a new document. 102 | 103 | .Release Notes Template 104 | [source,asciidoc] 105 | ---- 106 | = Asciidoctor x.x.x Release Notes 107 | Author Name 108 | _Release Date_ 109 | :toc2: 110 | :source-highlighter: 111 | :icons: 112 | :sectanchors: 113 | // Additional front matter, attributes, and references 114 | 115 | //// 116 | * Based on the Release Notes Template 117 | * Copyright (c) 2013 Sarah White and the Asciidoctor Project 118 | * Licensed under the MIT License 119 | * http://github.com/asciidoctor/asciidoctor/blob/master/LICENSE 120 | * Version 0.1.0.RC1 121 | * 122 | * http://www.github.com/asciidoctor/asciidoctor-documentation 123 | //// 124 | 125 | // Insert introduction paragraphs here 126 | 127 | == Installation and Upgrade Notes 128 | 129 | == New and Noteworthy/Highlights/What's New 130 | 131 | === Feature 1 title 132 | 133 | === Feature 2 title 134 | 135 | === Feature 3 title 136 | 137 | === Feature X title 138 | 139 | == Additional Features and Changes/Minor Features and Changes/Other Features and Changes 140 | 141 | * minor change 142 | * minor change 143 | * minor change 144 | 145 | == Changelog 146 | 147 | xxx issues were fixed in Asciidoctor x.x.x. 148 | 149 | * {URL Ref}[Issue-#] Issue title or 1 sentence description 150 | 151 | == Deprecations 152 | 153 | === Deprecated feature 1 title 154 | 155 | === Deprecated feature X title 156 | 157 | == Potential Breaking Changes 158 | 159 | === Breaking change 1 title 160 | 161 | === Breaking change X title 162 | 163 | == Contributors 164 | 165 | This Asciidoctor release would not have been possible without contributions from the following people: 166 | 167 | * Contributor Name 168 | ** Contribution 1 169 | ** Contribution 2 170 | * Contributor Name 171 | ** Contribution 172 | 173 | == Known Problems 174 | 175 | These issues, discovered after its release, affect Asciidoctor x.x.x. 176 | 177 | * {URL Ref}[Issue-#] Issue title or 1 sentence description 178 | 179 | == Feedback and Help 180 | 181 | The Asciidoctor Project is developed to help you sucessfully write and publish your content. 182 | But we can't do that without your feedback! 183 | We encourage you to ask questions and discuss any aspects of the project on the mailing list or IRC. 184 | 185 | If you discover errors or ommisions in the source code, documentation, or website content, please don't hesitate to submit an issue or open a pull request with a fix. 186 | The Code and Content Contributor Manual provides detailed information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project. 187 | New contributors are always welcome! 188 | ---- 189 | 190 | == Credits 191 | 192 | This guide was influenced by the release notes published for {http://www.gradle.org/docs/current/release-notes}[Gradle], {http://www.gimp.org/release-notes/gimp-2.6.html}[Gimp], {http://guides.rubyonrails.org/2_3_release_notes.html}[Ruby on Rails], {https://cwiki.apache.org/confluence/display/OOOUSERS/AOO+4.0+Release+Notes}[Apache OpenOffice], and {http://developer.android.com/sdk/RELEASENOTES.html}[Android SDK]. 193 | -------------------------------------------------------------------------------- /templates/tutorial-template.adoc: -------------------------------------------------------------------------------- 1 | = Tutorial Guide and Template 2 | Sarah White 3 | 4 | Tutorials demonstrate how to do something, such as complete a task, use a feature, run a process, or navigate an interface. 5 | 6 | == Audience 7 | 8 | Targets general new users and new users of advanced topics 9 | 10 | == Writing style 11 | 12 | *General* 13 | 14 | * Concise 15 | * Conversational 16 | * Keep the scope narrow 17 | 18 | *Title* 19 | 20 | The title of the tutorial should directly state the goal of the tutorial. 21 | The tutorial's goal should be narrow and specific. 22 | 23 | Yes: 24 | 25 | How to insert and style images in your document. 26 | 27 | Yes: 28 | 29 | How to highlight sourcecode in your document. 30 | 31 | No: 32 | 33 | How to use Asciidoctor. 34 | 35 | *Purpose* 36 | 37 | Simply state the purpose of the feature or process you will be demonstrating. 38 | Make sure to define any terms that new users may not be familiar with. 39 | Mention any prerequisites the user needs. 40 | 41 | *Demonstration* 42 | 43 | * Detailed step-by-step instructions demonstrating the tutorial's goal 44 | * Ambiguity kills tutorials 45 | * Don't make assumptions about the users knowledge level or setup that you don't state clearly at the beginning of the lesson 46 | * Executable code examples with callouts and/or screenshots (the best way to show the user what to expect and how to do it) 47 | 48 | *Review* 49 | 50 | Briefly conclude the tutorial by reminding the user what they learned and then direct them to the next tutorial and additional resources. 51 | 52 | == Template 53 | 54 | The template below lays out the basic structure of a tutorial. 55 | 56 | Text marked by +==+ indicates a major topic. 57 | Text marked by +===+ or more designates steps within the topic. 58 | 59 | .Tutorial template 60 | ---- 61 | = Tutorial title 62 | 63 | == Purpose/definition of the process, feature, etc. that will be explained 64 | 65 | == Step-by-step demonstration 66 | 67 | * steps are typically best shown as examples and screenshots 68 | * use callouts 69 | 70 | === Step 1 71 | 72 | === Step 2 73 | 74 | === Step 3 75 | 76 | === Step X 77 | 78 | == Review/Reiterate tutorial goal and what reader learned 79 | 80 | == Navigation to next tutorial and/or links to additional resources 81 | ---- 82 | 83 | == Testing 84 | 85 | Once you've written your tutorial, try it out. 86 | Follow the steps you wrote, word for word, to ensure that you didn't forget any details. 87 | Better yet, ask someone else to follow it and provide feedback. 88 | -------------------------------------------------------------------------------- /templates/user-manual-template.adoc: -------------------------------------------------------------------------------- 1 | = User Manual Guide and Template 2 | Sarah White 3 | 4 | CAUTION: This template is not finalized! It is a working draft, and it would love your input! 5 | 6 | A User Manual is a complete reference guide describing *how to use the application*. 7 | 8 | The User Manual: 9 | 10 | * describes each feature of the application, its benefits, and how to use the features that support each benefit 11 | * defines terms, processes, attributes, options, styles, and configurations 12 | * supports the processes and features showcased with executable code examples and screenshots 13 | * provides troubleshooting tips 14 | * provides clear, intuitive navigation directing readers to the next usage step(s) and additional resources 15 | 16 | == Audience 17 | 18 | New, intermediate, and experienced users of all technical backgrounds 19 | 20 | == Writing style 21 | 22 | *General* 23 | 24 | * Conversational 25 | * Step-by-step directions (don't make assumptions about the users knowledge level or setup that you don't state clearly at the beginning of the lesson) 26 | * Abundant executable code examples with callouts and/or screenshots (the best way to show the user what to expect and how to do it) 27 | 28 | *Chapters and Sections* 29 | 30 | Each chapter and section concentrates on a benefit of the application. 31 | 32 | To explain each benefit and its features, each chapter and section should include: 33 | 34 | * working examples 35 | * definitions 36 | * associated attributes, options, styles 37 | * output and backend variation considerations 38 | * troubleshooting steps and solutions 39 | 40 | == Template 41 | 42 | The template below lays out the basic structure of the Asciidoctor Core user manual. 43 | 44 | Text marked by +==+ indicates a page or chapter title. 45 | Text marked by +===+ or more designates sections within that chapter. 46 | 47 | .User Manual Template 48 | ---- 49 | = Title page 50 | 51 | == Copyright and license page 52 | 53 | == How to navigate the manual 54 | 55 | == Table of Contents 56 | 57 | Part 1: Introduction to Asciidoctor 58 | 59 | == What is Asciidoctor? 60 | 61 | === Major benefits 62 | 63 | Describe the primary benefits and supporting features of the application. 64 | 65 | === Compare to MarkDown 66 | 67 | === Compare to AsciiDoc 68 | 69 | Part 2: Quick starts 70 | 71 | == Installation quick start 72 | 73 | == Usage quick start 74 | 75 | == Syntax quick start 76 | 77 | == Custom backend quick start 78 | 79 | Part 3: Getting started 80 | 81 | == Installation 82 | 83 | === Installation requirements 84 | 85 | === Getting and installing the gem 86 | 87 | === Extensions and options 88 | 89 | == Commandline usage 90 | 91 | === Basic commands 92 | 93 | === From --help 94 | 95 | == API Usage 96 | 97 | === Basic commands 98 | 99 | == Output formats 100 | 101 | Part 4: Writing your content 102 | 103 | == Text Editor 104 | 105 | == Basic document anatomy 106 | 107 | === Header, Title and Author 108 | 109 | === Text and Paragraphs 110 | 111 | ==== Substitutions 112 | 113 | === Sections 114 | 115 | === Links and Cross references 116 | 117 | == Content Types 118 | 119 | === Lists 120 | 121 | === Tables 122 | 123 | === Blocks 124 | 125 | === Admonitions 126 | 127 | === Images and Videos 128 | 129 | Part 5: Enriching your content 130 | 131 | == Attributes 132 | 133 | === Document attributes 134 | 135 | == Metadata 136 | 137 | === Chunking 138 | 139 | == Sourcecode highlighting 140 | 141 | == Icons and Callouts 142 | 143 | == Images Dir 144 | 145 | == Includes 146 | 147 | Part 6: Navigating and referencing your content 148 | 149 | == Mapping content 150 | 151 | === Table of Contents 152 | 153 | === Section links 154 | 155 | === Index 156 | 157 | == Referencing content 158 | 159 | === Footnotes 160 | 161 | === Bibliography 162 | 163 | Part 7: Preparing your content for production 164 | 165 | == Previewing your content 166 | 167 | === Guard/Live viewer 168 | 169 | == Output selection 170 | 171 | List most options here but only go in depth on the common ones 172 | 173 | === HTML 174 | 175 | === DocBook 176 | 177 | * 5.0 178 | * 4.5 179 | 180 | === PDF 181 | 182 | == Slideshows 183 | 184 | === Deck.js 185 | 186 | == Custom backends 187 | 188 | == Stylesheets 189 | 190 | === Default 191 | 192 | === Stylesheet factory 193 | 194 | === Custom stylesheets 195 | 196 | == Styling DocBook and PDF output 197 | 198 | Part 8: Producing and publishing your content 199 | 200 | == Production 201 | 202 | === Locally 203 | 204 | === Multipart books and large documents 205 | 206 | == Publishing 207 | 208 | === Repositories 209 | 210 | === Static website generators 211 | 212 | Part 9: Conversions and migrations 213 | 214 | == Converting Markdown *to* Asciidoctor 215 | 216 | == Migrating from AsciiDoc to Asciidoctor 217 | 218 | Part 10: Build integrations and implementations 219 | 220 | == Java 221 | 222 | == Gradle 223 | 224 | == Maven 225 | 226 | == JavaDoc 227 | 228 | == Javascript 229 | 230 | == Yard 231 | 232 | == Rdoc 233 | 234 | Part 11: Conclusion 235 | 236 | Part 12: Resources 237 | 238 | == FAQ (Frequently Asked Questions) 239 | 240 | == Additional resources list 241 | 242 | == Glossary 243 | 244 | == Appendices 245 | 246 | == Index 247 | ---- 248 | --------------------------------------------------------------------------------