expand a page
You can expand a page that someone has started by expanding the definition, adding one or more new sections, or add to an existing section.
- expand (and/or simplify) a definition to include the IndieWeb relevance of the term and please minimize use of jargon (at link it if you must include it).
The top of a page should be simple, direct, and consider the audiences that are new the IndieWeb.
Beyond that, a page and its sections noted above should be easy so understand and use by new indieweb users, WordPress site users, and developers.
To better understand these audiences and needs, consider:
- Does the page make sense to an indieweb user and help them understand why something matters?
- Does the page make sense to someone using WordPress and how they can improve their blog?
- Does the page make sense to developers and provide a quickly understandable reason why they should care and how to implement it with examples including screenshots?
Most pages could use expansion of their existing sections.
- adding IndieWeb Examples - if you find a page for a technology you support on your site, or a project you use on your site, add yourself to the "IndieWeb Examples" for that page
- add issues and questions (for FAQs)
- collect questions/answers from chat and add them to the appropriate wiki page
Most pages have (or could use) sections like the following (in this order)
- How to
- IndieWeb Examples
- Silo Examples
- See Also
Pages about silos, other services, and software projects sometimes have:
- IndieWeb Friendly (support, compatibility, best practices etc.)
Do not add empty sections. If you have surfficient experience (and have asked in a channel for input), you may add stub sections that indicate there is "No known reason why" or "Unknown how to" or "How to still being figured out per brainstorming" etc.
Reorganizing Into Sections
Pages often have raw (paragraphs of text) content. Try to organize the existing content of a growing page into the above common sections as needed.
Brainstorming about how to better expand pages.
New Common Sections
As we identify patterns or needs, we may find it useful to adopt conventions for additional common subsections
How does this work
For user-feature pages:
In between the users that want things to "just work" (and don't care about plumbing), and developers who actively want to develop, install, or deploy things, there folks who are curious, who want to understand how something works before they will use it, personally commit to using it, or make a habit of using it. Captured here as a brainstorm from this chat between Rose and Tantek: https://chat.indieweb.org/meta/2020-01-22#t1579682020915200
For this "curious crowd", it may help to have an explicit section on user feature pages (e.g. note, reply, etc.) which explicitly says How does this work that explains the first-level of implementation details for that user feature, mentioning the specific technologies, standards, or services involved, and link to their specific pages for any further why or how-to questions.
This section probably belongs right after the "Why" section of such pages.
What can this do
It may help to provide a user-centric focus up front, like right after the definition, that specifically summarizes the compelling user-features (use-cases) that a technology solves or helps to solve, and or helped drive the design of that technology in the first place!
This is kind of the inverse of the "How does this work" section, and thus should link to the specific user-feature pages.
This section probably belongs right after the definition, in order to set an immediate broader user-centric context for understanding any particular technology.