ContextQMD
Back to Super Productivity

Wiki Structure and Organization

docs/wiki/0.00-Wiki-Structure-and-Organization.md

18.4.46.1 KB
Original Source

Wiki Structure and Organization

This wiki is still in its early stages and is more of a skeleton that defines what will be written and how the documentation will take shape. See [[0.-Meta-Diataxis]] for a conceptual introduction to the documentation framework.

Planned Structure

The note numbering system currently in use is a temporary measure to keep things organized and sorted while the content is built up. Eventually the numbers can be stripped out leaving just the first one since this can disambiguate a "How-To" note from a "Reference" note for example.

The wiki will incorporate both user-focused notes as well as developer-focused notes. So long as good organization, linking, and naming of notes is maintained it should not be difficult to find relevant information. The sidebar will be essential as a Table of Contents.

1. Quickstarts

This section contain Tutorials/Playbooks/Quickstarts. These are intended to teach and will draw upon material in other sections as needed to achieve that goal. The first, and at present only, Quickstart is [[1.01-First-Steps]]. It is very similar to this article by Johannes. Some of the articles on the Super Productivity site could be adapted such that they contain more interlinking with the wiki:

Johannes has created some content that don't quite fit into a wiki-structure but is related to "Quickstarts" in spirit. Here are a couple examples:

How to Write Quickstarts

The 1.XX sections should strive to follow these guidelines

By following these recommendations, you will be able to write a good-quality Quickstart:

  • Add the Quickstart to the title to guide the reader.
  • Teach by doing.
  • Use a friendly and professional tone.
  • The learning objective should be apparent from the beginning. Setting expectations from the start allows the learners to see themselves building towards the completed goal as they work.
  • Do not omit the “obvious.” Your learners follow the quickstart because they do not know about that topic or product.
  • Every step the learner follows should produce an understandable result, however small.
  • Your Quickstart should work for all users every time. This means you must consider different types of devices and software and test your Quickstart once a year to ensure it is updated.
  • Be specific about actions and outcomes.
  • Explain what’s necessary and nothing more. Your guidance must remain focused on achieving the stated learning objective.

2. How-To

This will contain a substantial number of notes. These notes will tell you what to do with minimal explanation. They will include more mechanical things such as how to...

  • install the app
  • create/manage tasks, tags, projects
  • backup and restore data
  • find more information
  • rate the app 5 stars :)

... as well as more complicated things such as how to...

  • build the app
  • work with task-issue integrations
  • configure various sync backends
  • contribute to this wiki
  • manage time sheets and work logs
  • submit issues/PRs

How to Write a How To

The 2.XX sections should strive to follow these these guidelines.

There is an assumed "How to..." preceding 2.XX note titles.

By following these recommendations, you will be able to write good quality how-to guides:

  • Describe a sequence of actions. A how-to guide contains a sequence of actions that have an order.
  • Solve a particular task. The problem or task is the concern of a how-to guide: stick to that practical goal.
  • Do not explain concepts—link to other documents for further explanation.
  • Omit the unnecessary. Practical usability is more helpful than completeness.
  • Pay attention to naming. Choose action-based titles that say precisely what the how-to guide shows, such as “Import A Course” or “Copy And Paste Course Content.”

3. Reference

  • Keyboard Shortcuts
  • User Data Location
  • Known Incompatibilities?
  • API

How to Write Reference Material

The 3.XX sections should strive to follow these these guidelines.

  • Do nothing but describe. References have one job: to explain and do that accurately and comprehensively.
  • Be accurate. These descriptions must be accurate and kept up-to-date.
  • Provide examples. It is a valuable way of providing illustrations that help readers understand the references without becoming distracted from the job of describing them.
  • The documentation structure should mirror the product’s structure so the user can work their way through it simultaneously. It doesn’t mean forcing the documentation into an unnatural structure. What’s important is that the documentation should help make sense of the product.
  • Be consistent in structure, language, terminology, and tone.

4. Concepts

  • What is a concept? Answers a question.
  • Make connections to other things.
  • Provide background and context.
  • (About) Topic should be implicit.

How to Write a Concept

The 4.XX sections should strive to follow these guidelines.

There is an assumed "About..." preceding 4.XX note titles.

Meta and Maintenance

  • [[0.01-Style-Guide]] — markdown and formatting for the wiki.
  • [[0.02-Wiki-QA-and-Maintenance]] — linting and link checking.