[Pitch] DocC Init Command - Catalog Templates

Development Swift-DocC
1

Hi everyone! - I'm excited to introduce a new command that's aimed at enhancing your starting experience with DocC - docc init .

docc init aims to make it easier and faster to start with conceptual documentation (article-only) catalogs by providing a starter folder structure and content template with blueprints on good practices regarding documentation creation with DocC.

Motivation

Setting up a DocC catalog is the first step needed to start writing documentation, this is why we want to reduce the entry barrier, making this an easier and effortless process.

While Xcode currently offers the capability to generate catalog templates for API documentation, users aiming to create article-only catalogs have to manually establish the folder structure, and create the `.docc extension folder and markdown or tutorial files. Furthermore, they must determine the organizational structure for their project and search in the DocC documentation how to incorporate a technology root, which serves as the top-level article file. Providing an initial template alleviates the necessity of memorizing and executing these manual steps.

Proposed Solution

Command Usage

DocC Init generates a straightforward catalog template with a recommended file structure, alongside prepopulated placeholder files to facilitate the commencement of documentation creation.

The init command currently takes the following form:

docc init 
   --catalog-output-path <output path dir> 
   --documentation-title <documentation title>
   --include-tutorial

Here's a breakdown of the command options:

  • --catalog-output-path <output path dir> Specifies where to store the catalog. The default is the current directory.
  • --documentation-title <documentation title> Sets both the name of the catalog directory and the top-level page. The default title is "Documentation".
  • --include-tutorial (optional). When provided, it incorporates a tutorial template into the resulting catalog.

Template Content

Executing this command results in the creation of a DocC catalog with the following folder structure.

-
|_ Documentation.docc
     |— Documentation.md
     |— Essentials
     |    |— getting-started.md
     |    |— more-information.md
     |    |_ Resources
     |- Tutorial
     |    |— table-of-contents.tutorial
     |    |— tutorial-chapter.tutorial
     |    |_ Resources
     |_ Resources
          |_ DocC@2x.png
          |_ DocC~dark@2x.png

The top-level article provides an example of how to incorporate images, manage content curation, and include the technology root directive.

# Documentation

@Metadata {
  @TechnologyRoot
}

<!--@START_MENU_TOKEN@→Summary<!—@END_MENU_TOKEN@-->

## Overview

<!--@START_MENU_TOKEN@→Overview<!—@END_MENU_TOKEN@-->

@Image(source: "DocC.png", alt: "An illustration of the DocC logo.")

## Usage Instructions

To start previewing this documentation run:
`docc preview ___CATALOG_OUTPUT_PATH___`

To generate a doccarchive run:
`docc convert ___CATALOG_OUTPUT_PATH___ -o ___CATALOG_OUTPUT_PATH___`

## Topics

### Essentials
- <doc:getting-started>
- <doc:more-information>

Here, ___CATALOG_OUTPUT_PATH___ will be replaced with the output path of the documentation.

The article is designed to just give some initial directions, but without overloading the template with an excessive amount of content.

Open Questions

  1. Are there specific elements that developers would find useful to have preconfigured when initiating this type of documentation? (e.g. a directive or a markdown example).

Future Directions

We are considering the implementation of this command in the DocC-Plugin, where the generated catalog will be tied to the targets defined in the developer's package.

Furthermore, we view this as a chance to incorporate additional templates into DocC. This would involve integrating usage scenarios and directive examples while providing practical demonstrations of the different formatting options available. By doing so, we aim to inspire the development of more comprehensive documentation with a conceptual focus.

The initial implementation of docc init is currently under review in this pull request:

I’m looking forward to hearing your thoughts about this!

-SofĂ­a

14 Likes
2

I love this idea, Sofia! This will make it much easier for developers new to DocC to get started quickly. This use case reminds me a lot of how the Ruby on Rails framework makes it easy to get started on a new web project. Here's an example:

% rails new my_web_project
etc...
      create  app
      create  app/assets/config/manifest.js
      create  app/assets/stylesheets/application.css
      create  app/channels/application_cable/channel.rb
      create  app/channels/application_cable/connection.rb
      create  app/controllers/application_controller.rb
      create  app/helpers/application_helper.rb
      create  app/javascript/channels/consumer.js
      create  app/javascript/channels/index.js
      create  app/javascript/packs/application.js
      create  app/jobs/application_job.rb
      create  app/mailers/application_mailer.rb
      create  app/models/application_record.rb
etc...

Notice how Rails displays all the new subdirectories and code files it creates. This is a nice way for the developer to know what just happened, and a great way to introduce them to the Rails project structure in case they aren't familiar with that yet.

I think it would be equally helpful for the docc init command to show the new DocC project structure in a similar way. Possible in addition to the "A new documentation catalog has been generated at..." message docc init could write the names of the new subdirectories and files it created to stdout.

5 Likes
3

Sounds like a good idea :slight_smile:

I'll mention this blog post, because it contains useful DocC tips I was not aware of.

1 Like
4

I have a few different concerns about this init command:

  • People may find this command and think that they should use it to create a catalog for their Swift package, resulting in a setup that builds without warnings but that has two root pages which probably isn't right for the developer.

  • Creating a catalog for tutorials also adds articles under a separate technology root. This setup probably isn't right for the developer because there's no common navigation between the article hierarchy and the tutorial hierarchy. If the catalog is intended for tutorial content, then the articles should probably use the @Article DocC directive so that all content is in the tutorial hierarchy.

  • After creating the initial template, the command doesn't help the developer if they want to add more tutorial content to their catalog. This means that if the tutorial didn't include the optional assessment, the developer still has to go to the DocC documentation to learn about the @Assessments directive and add it.

I think that the choice between article-only or tutorial-only should be explicit and that there may be some alternatives that's worth considering.

Looking at this excerpt from the Motivation section

I can identify three different problem statements:

  • The developer has to create a directory with a ".docc" extension and add various documentation files to it.

  • If the developer wants to create article-only documentation they much know to mark one of the articles as a technology root.

  • If the developer wants to create tutorial content they have to know which tutorial files and tutorial directives are required to display a minimal amount of tutorial content.

(DocC doesn't impose any organizational structure within the catalog)

Additionally I'll add that if the developer wants to add more tutorial content, use optional tutorial features like assessments, or use custom tutorial layout directives, the developer has to know that these directives exist and where they are supported and the developer has to add those directives to their content.

Setting aside the tutorial problem statements for a moment. In my opinion the biggest issue with article-only documentation today is that building documentation for a catalog full of miscellaneous markdown files without an explicit technology root doesn't do what most developers would expect. In the current release (5.9) this silently results in a documentation archive with no pages. On the "main" branch and in the upcoming 5.10 release this raises a warning that you added to DocC:

warning: No TechnologyRoot to organize article-only documentation.

Article-only documentation needs a TechnologyRoot page (indicated by a TechnologyRoot directive within a Metadata directive) to define the root of the documentation hierarchy.

This lets the developer know that the documentation hierarchy is missing a root and how to fix it.

I feel that there's more we could do here to address the "TechnologyRoot" problem. For example, trying to predict people's expectations for building documentation for a catalog with only articles;

  • if there's only a single article, DocC could consider that as the root.

  • if there are multiple articles, DocC could synthesize a root and auto curate all articles top-level under that synthesized root page. (If some of the articles had manual curation DocC's existing auto curation doesn't auto curate a page that's already manually curated.)

I feel that doing this would alleviate most of the issues of getting started with article-only documentation in DocC — although the developer would still need to create a directory with a 'docc' extension and add markdown files to it. This isn't hard to do but the developer would need to know that it's needed.

Coming back to the problem of getting started with tutorials. The minimal data to build any tutorial is two files with 'tutorial' extensions with ~10 lines of directives in each file. Even if the developer knows what directives they need to add in each file, adding them is not a smooth getting started experience. This is where I can see templates coming in handy.

That said, getting started with a minimal tutorial project is only part of the problem. As the developer adds more content to the tutorial they'll likely want to add other files — for example "tutorial article" files (using @Article) — or other directives (for example @Assesment). The starting template could contain a wide variety of directives and surrounding content that explain what each directive is for but starts feeling like documentation, or a tutorial, to me.

The DocC documentation has an article about writing tutorials and individual documentation for each tutorial directive but there's a lot to explain about writing tutorial content and tutorials are very visual.

I personally feel that much of the getting started experience for tutorials could be solved with a tutorial about writing tutorials. The "project files" for that tutorial could include both the minimal getting started point and the final built-up tutorial with a wide variety of tutorial content.

It may be that built-in getting started templates is still the preferred solution but I feel that there are a handful of alternatives that are worth discussing.

1 Like
5

People may find this command and think that they should use it to create a catalog for their Swift package, resulting in a setup that builds without warnings but that has two root pages which probably isn't right for the developer.

In practice, the recommended way to work with DocC for packages is through the DocC plugin. As outlined in future directions, the plan is to introduce a command that generates a catalog for a specific target while omitting the technology root directive. When you use this command, it will leverage the same templating system as Swift-DocC but adapt it to the user needs by removing the technology root from the generated catalog.

Creating a catalog for tutorials also adds articles under a separate technology root. This setup probably isn't right for the developer because there's no common navigation between the article hierarchy and the tutorial hierarchy. If the catalog is intended for tutorial content, then the articles should probably use the @Article DocC directive so that all content is in the tutorial hierarchy.

One possible solution is to provide two templates: one focused on articles and the other on tutorials. This can eliminate confusion and offer a more organized structure. You can initiate the tutorial template using the following command:

docc init --catalog-template tutorial

I like this idea, but I'm curious to hear what the community thinks about it.

After creating the initial template, the command doesn't help the developer if they want to add more tutorial content to their catalog. This means that if the tutorial didn't include the optional assessment, the developer still has to go to the DocC documentation to learn about the @Assessments directive and add it.

You're correct that the command may not provide guidance on optional elements like the @Assessments directive. These templates are intended as starting points, and it's still advisable to refer to the DocC documentation for a deeper understanding of available directives. It's a good idea to consider adding a link to the DocC website Documentation within the template for easy reference.

I believe it's valuable to pivot from the original proposal. One key suggestion is to divide articles and tutorials into two distinct templates. Additionally, we should revisit and refine the content within the tutorial template for improved clarity and usability.

Thanks David!

6

My concern is that a developer may do something that's not recommended without realizing it and put themselves in an unexpected situation and have a bad experience because of it.

If a developer find the docc init command—for example after running docc --help— there is nothing in the docc init --help output that tells the developer that this command is only intended for article-only documentation.

Can you share more abut those plans? Would docc init be used to create both documentation catalogs for source code and article-only documentation catalogs?

Even if the docc init command won't support creating documentation catalogs for source code at first it helps to have a sense of what the common line arguments would be so that the init command can grow to include those flags in the future.