Project style guide

Styles, processes, and glossary

Note:
The guideline examples appear both in the published format (as figures) and in the DITA source files (as annotations).

DITA/xml

  • "About this topic" section: Archive and remove this section when the information collection is published.
  • "About this topic" section: Include either a (1) "migrated source" or (2) a "new-topic" note for all topics.
    Example
  • Audience: Label all sections as either external or internal.
    Example
  • Authors: Include author information for all project collaborators, both human and AI.
    Example
  • Content verification: Include the "not verified" warning message in EVERY content topic unless/until it has been verified by a human SME (Subject-matter expert).
    Example
  • Dates: Use ISO8201 format (YYYY-MM-DD) for all dates. When changes to a file are made, update the "modified" date manually.
    Example
  • "For more information" section: For external information sources, include name and top-level website URL (NO direct link) or publisher name and date, if known.
    Example
  • Short descriptions: Do not include a short description in concepts—only in container topics.

Project text

Try to stick with a factual but interesting approach that would appeal to general audiences. Avoid anything propagandistic that might be written or promoted by business or real estate groups, or other local or regional special-interest groups.

Project images

  • Label: Label all images (in the title and alt text) with year created (usually 2003 or 2025) and include source ("maker"), if known. Most are by the authors/creators or Serrano/Parker (Serrano Associates or Parker Development.)
  • Scale: scale down larger images for initial presentation; by default (in webhelp responsive) the larger version of a given image will open when user clicks the scaled-down version.
  • Size: Be sure all included images have a maximum longer dimension of 1280px.
    Example

Development process

  • DITA/xml: The beta version of this project is being written in DITA/xml using the oXygen editor.
  • Collaboration (human/AI assistant):

Production process

  • WebHelp Responsive: The beta version of this project is being published to oXygen's version of WebHelp Responsive and posted to the authors' vrjassociates.us website.
  • Sections labeled as audience="internal": Remove all topics or sections written for internal audiences only.

Glossary

Term Definition
Alpha-level/Beta-level project Early and test versions of a project. Alpha is for initial feedback; beta is more complete, ready for broader testing or release.
Collaborative workflow A process where people and AI systems work together to create, review, and update content.
DITA/xml DITA (Darwin Information Typing Architecture) is an XML-based standard for organizing and publishing topic-based information.
GenAI (Generative AI) Artificial intelligence that creates new content, such as text, images, or code, in response to prompts.
Knowledge base (KB) A central digital library of organized articles, FAQs, and documents used to answer questions and support projects.
Machine translation Automatic translation of text from one language to another using AI software.
RAG (Retrieval-augmented generation) An AI technique that first searches a knowledge base for useful information, then generates an answer using both the results and its own training.
WebHelp Responsive Documentation published as interactive, mobile-friendly web pages for easy public access and searching.
XML editor (e.g., oXygen) A specialized software tool for creating, editing, and checking XML-based documents and technical content.

About this topic

editor comments (2025-10-31):
- The glossary section of this topic collects essential terms used throughout the El Dorado Hills community information project and related collaborative projects. - Entries are kept concise to support quick reference; more detailed explanations may be added in future revisions or in a dedicated main glossary topic. - To suggest additions or edits, please contact the project editors.
editor comments (2025-10-29):
This is a new topic in 2025.