Wiki: Initial topics + points to cover

[rphair]

This issue is a call for anyone interested in the CIP editing process to suggest topics for a new Wiki introduced at today's biweekly CIP meeting to be posted at the standard repository URL: https://github.com/cardano-foundation/CIPs/wiki

• Suggestions can include items of any scale: from documentation sections to mere facts to be included or questions to be answered.
• A number of the items below overlap & it's not a problem to suggest further overlapping items.
• It may become a checklist at some point; depending on how many ideas are contributed.

I'm planning to post a draft of this content this week, so please update this issue ASAP with anything you think should be here.  Here are the main content items repeated from my originally proposed outline (posted here on the CIP Discord [invite if needed]):

• Workflow of CIP editors: both regular and irregular components
• Meetings: why we have them, what we do, how to prepare & follow up
• Community engagement: groups and suggestions for interacting with them
• Ethos: what the CIP process does and doesn't do (expanding on this from CIP-0001)
• Reviews: how specifically a GitHub review is processed when preparing to accept a CIP draft... this will also be directly useful to developer and community members engaging with the CIP process, including but not limited to those who may be "training themselves" for an eventual application as a CIP editor.

Much of the above will be re-tasked from my Medium article series beginning here (mainly from # 1 of these 3 articles), omitting whatever might be considered personal, political, or speculative: https://rxphair.medium.com/cardano-improvement-proposals-cips-introduction-from-an-insider-7b2f7cc94d01

suggestions from today's CIP editors' meeting

From @Crypto2099

• What does being a "CIP Editor" mean
• Why do I need a rationale and how do I write one?
• I like Cardanzo [sic], how can I help?

From @Ryun1

• why do we seek extensibile standards?
• "your first proposal"
• how to review
• CIP process history / context

Resolution responding to @rjharmon about target audience, allowing reader to "choose your own adventure":

• top level should have items of general interest & understandable by non-developers.
• navigation & questions should allow people to choose how they want to be involved:
  • as CIP readers?
  • as CIP writers?
  • as potential CIP editors?

My own reflection during the meeting:

• I have a good idea for something Cardano should do, or something I'm doing with it: should I post it as a CIP, a blog article, or a forum thread?

Editors reiterated our goal to get "tribal knowledge" (as characterised by @Crypto2099) out of our customary practice & beyond our habitual CIP reviewers + meeting attendees to take on visibility & accountability, eventually becoming (as I believe) part of our Cardano equity.

In writing this first set of pages my goal will be to outline these topics and provide (or repurpose from what's already written) preliminary material for each of them: enough to form a framework that others feel comfortable editing & extending, then to continue as a group effort.

cc @thenic95 @katomm @michaelpj @KtorZ @aleeusgr

[michaelpj]

I would think that quite a bit of this is a good fit for a CONTRIBUTING document in the repository? All the parts that talk about the workflow of how CIPs are produced, reviewed, and accepted?

[rphair]

thanks @michaelpj - I've added this to my TODO. Will find out in the meantime about the precedent for whether the relevant Wiki content should be duplicated or linked into CONTRIBUTING.md (please post if you have any suggestions).

According to open source standards it seems important that this document should stand alone in a cloned repo but I wouldn't want to duplicate too much content between CONTRIBUTING and the Wiki. 🤔

[aleeusgr]

A wiki and a contributing guide may be differentiated by the level of emotional engagement the reader has with the project . A person opening a contributing guide has a at least semi-conscious desire to contribute to the project which implies some level of emotional ownership. A wiki is more suited to people who are curious but not necessarily committed to doing something - driven by curiosity they are just exploring.

This difference becomes more or less important based on who is involved, or more precisely - on how you define your community. If the community is defined by individual human beings a wiki is a must have, since its better to rely on open initiative and avoid asking people to provide any inputs even if so indirectly as the need to open a contributing.md to access some crucial information like the comms channels, the workflow, etc.

Noticing dissatisfaction among some community members and reflecting on reasons and ways to mitigate in the future. The contributing guides I found tend to focus on technical aspects but miss out on the human engagement part, so I wrote a guide with its target audience being an unaffiliated developer who is interested in joining a working group. The guide aims to promote transparency and reflection in the reader, and the goals are to promote clarity of intent and prevent burnout among contributors. I hope it is insightful.

[Ryun1]

Another nice-to-have page on the wiki - a list of the top 10 most widely used/impactful CIPs.
Could act as a nice starting place for people to catch up on the key knowledge.

[KtorZ]

Wikis are notoriously hard to organize on Github, as there's no good way to arrange the sidebar of links (GitHub sorts them lexicographically which is often .. not the best way to organize the content).

Having said that, with a properly maintained "homepage" they can be bearable. I see wiki as good ways to record decisions or keep track of a logbook (e.g. https://github.com/input-output-hk/hydra/wiki/Logbook). It's usually a one-way type of communication (you cannot comment on a wiki, only read/receive information). The main advantage over a plain folder with files on the repository is that it makes edit a bit simpler as it can go through a different workflow.

• We could imagine moving the biweekly notes there, and also links to agenda of the various meetings.
• An F.A.Q. too, why not?

[rphair]

Posted now at: https://github.com/cardano-foundation/CIPs/wiki — a draft which incorporates my best CIP process writing to date & everybody's feedback. This will be a "living" document going forward so editors should feel free to begin making changes any time (entering any substantial additions or deletions on the Changelog page).

In that sense it is "finished" since editors should never stop updating it (all others are invited in the footer to submit issues & discussions to suggest content improvements). I think revisions are tracked (so we can see editing histories) but I haven't figured out how that works yet... maybe through a local git clone since I don't see it in the UI.

@rjharmon it begins according to your suggestion of a "Choose your own adventure", keeping the number of categories small by including a single section for authors + reviewers (since the criteria for reviewing a CIP I found were also the same principles used in writing a good CIP).

@Ryun1 therefore I hope the enumerated principles & checklist will suit first-time CIP / CPS writers... that was the intention in writing that section, so please confirm that you think it will work for first-time authors as well as giving reviewers more ways to toughen up the docs they choose to work with. (It should also therefore also be useful to get any new CIP editors up to speed quickly.)

@Crypto2099 it should also address your suggestions, including the one I've had to deal with on the Forum of when a submitted CIP is really better suited as some other kind of document: asking them preemptively and diplomatically to move inappropriate submissions else: with writing encouragement for all legitimate submissions following quickly afterward.

With the means of "contributing" fully documented now, I plan to follow up on @michaelpj's suggestion to post a CONTRIBUTING.md in the repo that mainly links to the Wiki. I'll post the PR here in case anyone has ideas about anything else to add (cc @aleeusgr).

@KtorZ you were right about the GitHub Wiki navigation being horrendous: one reason why the number of pages is small, and why the main pages have been kept with multiple sections rather than breaking up into greater number of pages that the Wiki nav can't really support. I had to try a bunch of outlines until I found one that worked. The FAQ style actually suited the whole document rather than the traditional "Wiki" notion of defining each term.

@katomm @thenic95 @weqanhet once there is confirmation all around by co-editors and potentially other stakeholders I'll submit a link to the CIP / Governance section on the Dev Portal to this new material.

Please post your confirmations that this serves as a baseline going forward, and definitely post any problems or corrections as soon as you are able.

[rjharmon]

Great job @rphair - thanks!

[rphair]

Thanks everybody for the confirmation of a Wiki that serves our existing needs, with room for further improvement according to editor inclination & by community request... and especially if our documented process ever changes.

Therefore I'm closing this issue and removing its link from the Wiki Footer, so that feedback is directed to the repository Issue queue & Discussion board.

To answer the question about revisions / changes:

• At least Editors will see (at the top of articles) a Page history button after clicking the Edit button (I don't know if this button appears for non-editor GitHub accounts), which allows 1 or 2 old revisions to be ticked & compared with the previous version or each other respectively.
• A git clone will also show a commit history to allow historical versions to be fully checked out locally.