# Sphinx: audience questions

I'm trying to list out questions that an audience, that is new to Sphinx, might have. This is roughly based on the audiences we've identified so far [in a GitHub issue discussion](https://github.com/sphinx-doc/sphinx/issues/9165).

Please don't try to answer the questions listed here, that's not what this document is trying to do.

Instead, we're trying to figure out roughly the kinds of questions those audiences would ask. Having this list can help us figure out whether our existing documentation makes it easy to answer them, to identify gaps and figure out changes accordingly.

To be clear, not all of these questions would need to be answered in a beginner tutorial. Instead, these are roughly "broad" questions that nearly everyone in that audience would have. We'll _(maybe)_ think about some "user journey" for each of these audiences later.

If you want to:

- Make an inline comment: Select some text, and you should see a way to add comments to the side.
- Add/Edit a question: click the "Edit" button on top, which should take you into an edit view. This document is written in Markdown, is publicly editable and has version history.

Cheers,
@pradyunsg

## Questions

### Common

These apply to all audiences.

1. What does the workflow looks like, when working with Sphinx?
2. How to "build the documentation"? -- the exact CLI invocations
3. Basics of reStructuredText (bold, italics, quotes, etc)
4. What ways do I have to structure the content? (headings, pages, toctree)
5. What ways do I have to cross-link/reuse content?
6. What does documentation generated with Sphinx look like?
7. How do changes in the "documentation sources" get reflected in the generated output?

### Audience-specific

#### New contributors to an OSS project, who are learning about how to work with the project's documentation; and starting with the tool (i.e. Sphinx).

Nothing beyond the common questions listed above.

#### People working at companies or large OSS projects that are tech writers or other non-developer roles, using Sphinx to create docs for a product

Nothing beyond the common questions listed above.

#### Developers at companies or OSS projects who are evaluating doc tools to standardize on, getting a "first experience" of Sphinx to evaluate it as a product

1. Does Sphinx provide the "basic" things that other tools do?
2. What are the features of Sphinx, that differentiate it from other tools? How do you use them?
3. What ways do we have to utilize our existing team's knowledge (eg: in Markdown for authoring, in web frontend for site design etc)?
4. How would we build customised/branded documentation sites?

#### Scientific users who are just wanting to use the standard tooling in the ecosystem to contribute to existing doc sets, and want to learn the various features

1. How to "build the documentation"? What are the exact CLI invocations?
2. How do I write a basic Sphinx documentation set?
3. How do I integrate Sphinx with all of the other tooling that I have?

#### Non-Python developers who are using Sphinx to document code in narrative and/or API documentation

1. How do I "connect" Sphinx with my $domain's tools?

#### Translators

1. How do I edit PO files?
2. How do the translate roles work?