P:Documentation/Naming Conventions: Difference between revisions

From Open Source Ecology
Jump to navigation Jump to search
(Created page with "== Intro == Clarify how topics in the wiki relate to each other, especially for: * Newcomers - see how things relate to each other * Contributors - know how to add new topics...")
 
Line 7: Line 7:
The idea is to use naming conventions based on BEMIT, a CSS naming convention. As applied to this wiki, I recommend these conventions:
The idea is to use naming conventions based on BEMIT, a CSS naming convention. As applied to this wiki, I recommend these conventions:


* Let there be 3 types of topics: process, object, and narrative
* 5 types of topics: process, object, narrative-folk, narrative-map, and narrative-view
* Let pages be named or tagged using the first letter of each type of topic, such as p- and o-
* abbreviate these types so that the first word is just a letter: P, O, Nfolk, Nmap, Nview
* Let there be 3 types of narrative topics: .n-folk, .n-map, .n-view. There will never be an n- topic.
* 3 types of relationships within naming conventions: parent&child, topicXtopic, and topic=>modifier
* Let there be a parent and children topics
* Titlecase topics, such as: "Documentation Standards" or "Global Village Construction Set"
* Pre-pend topics with the topic type, such as "P: Documentation Standards" or "Nmap: Global Village Construction Set"
* Nest child topics using the url / convention, such as "3D Printer/Frame"
* String neighboring topics using the X convention, such as "Nview: Disciplined Entrepreneurship X Priorities X Critical Path X Traction"
* Add modifiers using colons, such as "3D Printer/Frame: PVC Pipe"
* For objects with multiple modifiers, use the topic X topic convention, such as "3D Printer/Frame: PVC Pipe X v18.10" and "3D Printer/Frame: PVC Pipe X v18.11"
* For any topic with children, provide a glossary of children on that topic page
* For any topic with modifiers, provide a glossary of modifiers on that topic page
* For any topic with parents, provide a glossary of parents and "grandparents" on that topic page
* For any topic that exists on a Nmap or Nview, provide a glossary of related narratives on that topic page
* Automate the creation of these glossaries if possible. If needed, add it as a child that is a Nmap itself, like "3D Printer/Nmap: Glossary


== Priorities ==
To put this in action, I recommend first to start creating any new information using these conventions, then re-categorizing any information needed to onboard folks sufficiently to becoming true fans.
I think this includes creating the following pages:
* Nmap: Core Processes
* Nmap: Active Objects: 2018
* P: Onboarding/Email Sequence: 2018


=== References ===
=== References ===

Revision as of 18:57, 17 October 2018

Intro

Clarify how topics in the wiki relate to each other, especially for:

  • Newcomers - see how things relate to each other
  • Contributors - know how to add new topics to existing ones
  • Upkeep - manage complexity by prioritizing upkeep of some parts of the wiki over others and manage team energy

The idea is to use naming conventions based on BEMIT, a CSS naming convention. As applied to this wiki, I recommend these conventions:

  • 5 types of topics: process, object, narrative-folk, narrative-map, and narrative-view
  • abbreviate these types so that the first word is just a letter: P, O, Nfolk, Nmap, Nview
  • 3 types of relationships within naming conventions: parent&child, topicXtopic, and topic=>modifier
  • Titlecase topics, such as: "Documentation Standards" or "Global Village Construction Set"
  • Pre-pend topics with the topic type, such as "P: Documentation Standards" or "Nmap: Global Village Construction Set"
  • Nest child topics using the url / convention, such as "3D Printer/Frame"
  • String neighboring topics using the X convention, such as "Nview: Disciplined Entrepreneurship X Priorities X Critical Path X Traction"
  • Add modifiers using colons, such as "3D Printer/Frame: PVC Pipe"
  • For objects with multiple modifiers, use the topic X topic convention, such as "3D Printer/Frame: PVC Pipe X v18.10" and "3D Printer/Frame: PVC Pipe X v18.11"
  • For any topic with children, provide a glossary of children on that topic page
  • For any topic with modifiers, provide a glossary of modifiers on that topic page
  • For any topic with parents, provide a glossary of parents and "grandparents" on that topic page
  • For any topic that exists on a Nmap or Nview, provide a glossary of related narratives on that topic page
  • Automate the creation of these glossaries if possible. If needed, add it as a child that is a Nmap itself, like "3D Printer/Nmap: Glossary

Priorities

To put this in action, I recommend first to start creating any new information using these conventions, then re-categorizing any information needed to onboard folks sufficiently to becoming true fans.

I think this includes creating the following pages:

  • Nmap: Core Processes
  • Nmap: Active Objects: 2018
  • P: Onboarding/Email Sequence: 2018

References

How To

Examples

Retrieved from "https://wiki.opensourceecology.org/index.php?title=P:Documentation/Naming_Conventions&oldid=179860"