Mention DocWarp, Diataxis Framework; mention what the CLI client does
This commit is contained in:
parent
7ec68e3713
commit
94db8e73fb
22
README.org
22
README.org
|
@ -1,21 +1,29 @@
|
|||
#+TITLE: DocSpec
|
||||
#+TITLE: DocSpec and DocWarp
|
||||
|
||||
DocSpec provides a standard, predictable interface to access the [[https://diataxis.fr/][four different types of documentation]] for a project - tutorials (lessons), how-to guides (recipes), explanation (discussion), and reference (technical description).
|
||||
DocSpec provides a standard, predictable interface to access the four different types of documentation for a project, as defined by the [[https://diataxis.fr/][Diataxis Framework]] -
|
||||
1. tutorials (lessons),
|
||||
2. how-to guides (recipes),
|
||||
3. explanation (discussion), and
|
||||
4. reference (technical description)
|
||||
|
||||
DocSpec is
|
||||
1. a configuration file in your project root, specifying how to reach sections of your documentation, and associating symbols with them if desired
|
||||
2. a Common Lisp library to query the file
|
||||
3. a command line client built on the library
|
||||
4. an Emacs package, providing a =completing-read= interface
|
||||
|
||||
It is hoped that this tool will -
|
||||
1. make documentation more accessible to users, and
|
||||
DocWarp is
|
||||
1. a command line client (using DocSpec) to view the desired documentation for a project, in your preferred programs and formats
|
||||
2. an Emacs frontend to the same, providing a =completing-read= interface
|
||||
|
||||
It is hoped that these tools will
|
||||
1. make documentation more accessible to users
|
||||
2. make more projects aware of the [[https://diataxis.fr/][Diataxis Framework]], and incentivize them to structure their documentation according to its suggestions, which in turn would make their documentation easier to read, write, and maintain.
|
||||
|
||||
* Creating the file
|
||||
Below is what an example DocSpec file for the [[https://github.com/McCLIM/McCLIM/][McCLIM]] project might look like.
|
||||
|
||||
Each documentation type has topics it covers - in this example, each topic is a symbol, but they could also be strings.
|
||||
Each DocSpec file can list up to four types of documentation as symbols - =tutorial=, =howto=, =explanation=, and =reference=.
|
||||
|
||||
Each documentation type has topics it covers, e.g. =first-attempt=. In this example, each topic is a symbol, but they could also be strings. Documentation written in accordance with the Diataxis Framework is more likely to cover the same topics in different sections, so topics may be repeated between documentation types, but not within.
|
||||
|
||||
The documentation for each topic can be presented in one or more formats - a string, a PDF file, an HTML file, etc.
|
||||
|
||||
|
|
Loading…
Reference in New Issue