Aims of the wiki

[AbhiAgarwal]

What are the aims we are trying to achieve? I'm just interested to have bullet points

• Make it easy to keep knowledge/information in one place year after year.

What are the aims for an individual using the wiki on a weekly basis? a monthly basis?

@ethanresnick @KatyHerrick @freialobo

[ethanresnick]

I can jump in more here soon, but why don't you guys (@freialobo) take a stab at better defining the aims first. In particular, try to write the aims in a way that's specific enough to explain why we need the wiki (as opposed to just the Google Drive or the intranet).

[KatyHerrick]

Cons of Google Drive:

• Too much clicking; important documents are buried in folders of folders
  • Related: inflexible directory structure means that a doc can only live in one place. referencing another doc is messy.
• No emphasis on formatting
• Too easy to make accidental edits on what should be static documents (i.e. historical shared docs)

Note that I don't understand the intranet all that well!
Cons of the intranet (currently):

• No structure exists for best practices
  • Pages would have to adhere to a strict format (because of the required fields), which might limit the kind of best practices people are inclined to add
  • A blank page with no required fields would be just as bad as Google Doc
• Once added, finding the most relevant info in the API poses a huge design challenge
• Linking pages of info is difficult
  *A "links to" field for links to other best practices is messy... Preferably, we'd want the text to link to other directly

How the wiki solves these problems:

• Supports intuitive formatting that is flexible for each page's needs (i.e. Headers for each important section are required, but the content and nesting of the headers is up to the editor her/himself)
• Pages can link to each other as needed; pages can link to specific sections of other pages as needed
• Editing is simple, but getting to the editing page requires clear intent
• We don't have to build any additional structures on the intranet

Aims of the wiki:

• Be a user-friendly resource to find current best practices
• Be a historical hub for old lessons learned and retired initiatives

[ethanresnick]

@KatyHerrick Good list. I'd just add/clarify a couple things:

1. The primary con of having so many folders on Google Drive isn't that it requires extra clicking to find a document that you're looking for and that you know exists. (Search solves that.) The downside of folders is that it's impossible to see at a glance what documents exist in the first place, so you don't know to look for things that already exist and could be valuable. If the documents aren't easily discoverable, they won't be used.

2. Re "finding the most relevant info in the API poses a huge design challenge"... this isn't really true. It's no harder to design good discovery mechanisms for API data than it is for wiki data. The value of the wiki here is that it may be easier to code some of those interfaces by leveraging the wiki's existing codebase, whereas we'd have to code them more "from scratch" if using intranet data.

3. Re many of your other points: you're totally right that the wiki's design has many advantages, like better linking, and easier/inline editability by anyone. When it comes to having unstructured pages (i.e. flexible sections), this can be both an advantage and a downside. For example, you're right that structure can "limit the kind of best practices people are inclined to add", but it can also ensure that we add best practices in a standard way, which could be designed upfront to guide people to add the right information (e.g. what experiences led to the formation of the practice, which topics it's relevant too, etc). So, when we're deciding the content for the wiki, the trick is to figure out:

   1. What content types are better served by the wiki's capabilities?
   2. And, if some stuff is going to live in the wiki and some stuff in the intranet, how will people know where to go to find which types of content?

   Points one and two need to be balanced with one another. That is, we may have to define simple, broad rules for what content lives where (point 2), even if that means dividing the content not perfectly along the lines of what's best served by the constraints of each platform. (Though we can solve this tension somewhat by rigorously linking between the intranet and the wiki—even though that introduces it's own downside in terms of maintaining all those links.)

Aims of the wiki:

• Be a user-friendly resource to find current best practices
• Be a historical hub for old lessons learned and retired initiatives

Good, now we're talk about specific content types. One question: What do you mean by the distinction between "current best practices" and "old lessons learned"?

[freialobo]

This all sounds good. Additionally

• The Wiki helps with onboarding.

Katy and I talked about

• the distinction between "current best practices" and "old lessons learned"

And I think she means Say I have to plan Hackdays. Current best practices will be a How to organize Hackdays. Old lessons learned will be Advice from Abhi, Max, Nate etc

Example of each

Current best practices:

• Book a room in Courant
• Email the opportunities@cs.nyu.edu listserve

Old lessons learned

• Events on AngularJS tend to do very well
• Events about NodeJS tend to do very badly

[KatyHerrick]

Yes to Freia on the distinction b/t lessons and best practices!

What content types are better served by the wiki's capabilities?
And, if some stuff is going to live in the wiki and some stuff in the intranet, how will people know where to go to find which types of content?

Wiki/Intranet Relationship as defined by Katy

-The wiki holds descriptions of the club and how to run the initiatives. This is where background information about the club such as "What is DesignDays?" and "Who started Tech@NYU, and for what reason?" is stored. Historical semi-biographical information about the club doesn't have a clear application–it can't be coded into some kind of tool. In addition, the wiki contains how-to guides that will give timelines and will link to new tools that use data stored on the Intranet. The wiki will give advice from past organizers, which again, can't be turned into a "tool". Some things just need to be read and kept in mind. Nothing more needs to be done with it.
-The API stores data about our previous relationships and venues, and provides the tools for members to execute the best practices stored in the wiki. I admittedly am not the best at imagining what can be done with data, but I see the intranet as a set of tools that uses info from the database to make event planners' lives easier. When things like the "Venue Finder" are complete, it will be stated in the wiki: "At the beginning of the year, use the VENUE FINDER to book classrooms for recurring events." or "If your event is 1 week away and you have no venue, use the VENUE FINDER to find a last-minute location." Things like the "Event Feedback Form" will also live on the intranet, but then the lessons synthesized from it by whoever reads/analyzes the feedback will be put into the wiki manually in accordance with how the wiki is set up.

I just can't see feedback/lessons-learned being stored in the API in a minimal, accessible way. For ease of reading and maintaining organization, there will always have to be a human synthesizing the feedback and putting it into the wiki in a way that removes duplicate feedback.

[ethanresnick]

A few things:

1. As you point out, the intranet can definitely provide tools to enable eboard members to carry out the best practices described in the wiki. But I think it should go further and coerce people to follow some of those best practices. For example, if we know that a certain timeline works for planning events, the intranet should be automatically emailing people/the vp when they're falling behind on that timeline (e.g. if they don't have a venue in the api a week before their event). Or, if we know that it's really important to book a venue for an entire semester upfront, the copy and/or available fields or steps in the intranet should nudge people to do that.

2. A principle should be: put the best practices "as close as possible" to the places where board members will be going to carry out their duties, which is the intranet. Because, otherwise, people likely won't reference/remember the best practice. For example, if we have a step-by-step how-to guide for planing an event in the wiki, the odds that someone refers to that guide when scheduling their event don't seem that high to me. (But maybe I'm wrong?) On the other hand, building that guide into the "Add Event" flow in the intranet does seem like it would be used. By "building in the guide" I mean, e.g.: rather than writing down in a separate document "Make sure to email person x to get your poster on KDSN", the intranet would have a page that loads after you submit your event that would prompt you to upload your poster and would have a button for automatically emailing it to KDSN. That's prompting the best practice in the same place where the user already is.

3. I'm still not sure that the "best practices" vs. "lessons learned" distinction makes sense. If a lesson learned remains applicable, then it implies a best practice; if it's no longer applicable, we don't need to keep it. Right? So, I see Freia's list above as implying four best practices for planning a hack days, which could be grouped by tasks (as below) or chronologically.

   -. Picking the theme

   • Events on AngularJS tend to do very well [+ source data here, so that the person reading this can decide if it's still applicable; if not, it should go]
   • Events about NodeJS tend to do very badly [ditto]

   -. Marketing then event

   • Email the opportunities@cs.nyu.edu listserve
   • Etc...

4. All of my comments here and previously, I think, boil down to the following principles—which still don't provide concrete descriptions of what should go where; these are just principles. To apply them, we'll need to actually go through all the content we have and see where it fits. That said, I think the principles are:

   • Make a best practice automatic when you can. A best practice implemented in code is carried out every time.
   • If you can't make it automatic, promote it/nudge the user to do it through design, at the point when/where they're doing the task (accounting for situations where they may have to go away temporarily and come back to complete the best practice).
   • If you can't nudge them to do it or, as Katy pointed out, it isn't information that's directly actionable, then write it down somewhere where that it's easily discoverable (i.e. the wiki, or an orientation guide).
   • And, when considering whether to design a systematic nudge or automation for a best practice, balance the value of the nudge or automation against the likelihood that the best practice will change. If something looks likely to change, designing/coding it into the system may not be worthwhile (and could be counterproductive if the practice remains in code after it's no longer a best practice). Conversely, putting it in the wiki, where it's most editable, makes more sense.

So what do those imply for contents of the wiki? Like I said: not much, yet. We need to do a thorough content audit firts. But I think they suggest at least a few types of good wiki content:

• Narrative text about the club's or an initiative's history and purpose, which we want to encourage people to keep up to date, as Katy suggested.
• Text about our general organizational structure or modes of governance (why they are as they are)
• Best practices that we're still trying out, such that they don't yet warrant being more deeply engrained in code
• others?

[AbhiAgarwal]

I really enjoyed all your points here. I kind of understand your viewpoint now. However, I also am strongly opposed to using the intranet to define best practices. I totally agree that the intranet could be used to enforce these practices, but they must be defined somewhere. I believe that a section of the wiki is to define the best practices and document the historical nature of our club.

Points 1 and 2 (I kind of thought they implied similar things):

I feel like if we use the Intranet to define and apply best practices then we run into issues. Any change in the best practices (however critical) could take an extended amount of time to apply. In my mind this is because there could be a shift in how people use the Intranet because of this alteration in best practice - a change in the design itself. In this regard I would like the change to be made on the wiki, and then adjusted on the Intranet (whenever it's done).

I really like the idea of the Intranet/Feedback system emailing when things haven't been done. This is really important and I really think this would be really amazing. This would force people to fill out all the details in advance as well. Or to nudge them if they haven't created an event in a while. (Meaning their initiative is idle right now). I definitely agree that the Intranet is a huge plus point for that. However, I do believe that defining these deadlines on the Wiki is important. They can definitely be applied onto the Intranet, but a lead putting his/her thoughts down and being able to make changes on the wiki page is quite key. To me, this section of the Wiki is to clearly set and enforce guidelines for an event.

The intranet can follow how the wiki is defined, but having the wiki means that the infrastructure team has clear guidelines of what to build. In addition, the other individuals in teams also have the flexibility to make changes to reflect their new practices without having to worry about dealing with changes on the Intranet.

Point 3

From my understanding of talking to Freia - the best practices are more generalized, and don't have much to do with single events. They could be things like You should do X a week before. The others are reflections on things that can go wrong given certain conditions. They are not generally applicable, but they are in some cases. I would not count these as best-practices, but just observations that have been made regarding certain events.

Maybe NodeJS talk sucked due to many different reasons. It doesn't make sense to make this a best practice as it could have sucked because the weather was horrible. This goes down into an observation or lesson that is learnt. It's circumstantial - if that makes sense!

I think what I'm coming towards is

• Best practices need to clearly be defined somewhere. They can be implemented, but for flexibility they should be defined. The implementation can always reference the definition that has been made. To me this is like implementing the JSON-spec and actually defining the JSON-spec. The best practices is a specification. A specification that improves over time, and the implementations just follow it.

[KatyHerrick]

Coming back to this after a load of self-education about intranets, design, etc. and having completed much of the content audit!

@ethanresnick, as usual, you have great points in this chain. I understand and agree with your position about building best practices into the intranet a lot more now. I am going to do my best to propose a firmer notion of how to fit the existing content into the wiki/intranet/google drive divide. This is my proposal for how to work the best practices found in the existing content into the intranet, and how to keep future content split among google drive/wiki going forward.

Firstly, the existing content can be clearly divided into 3 categories:

1. Descriptions of the club, initiatives, overarching goals, and the like.
2. Meeting notes, interview notes, treasury budgets, atl
3. Reflections on past events, ideas for upcoming years, best practices and processes, atl.

1. Descriptions of things

The most obvious existence for the wiki. A place for new existing members to familiarize what tech@nyu does, and how their individual work contributes to our greater goal. Critical reading for new member orientation, and easy cut-and-paste descriptions of our work and mission to give to potential sponsors and speakers.

• Will live solely on the wiki.
• Will not be incorporated into the intranet in any way.
• Still coming up with a plan to structure the information into the wiki, taking into account changing visions and initiatives.
• Still coming up with a plan to encourage maintenance.

2. Ephemeral content (Notes, interviews, budgets)

I'm hesitant to express my opinion about this next part because I know record-keeping is important to the club. However, it is my belief that meeting notes and interviews with candidates should be considered "ephemeral content" and not stored long-term on the wiki nor the intranet. Of course, this information needs to be written and communicated somewhere, so here are two ideas:

1. Make data structures in the intranet that will enforce consistency in entering data. For meeting notes, I envision just a big text box (that supports markdown?) that is editable by all members. (Yes, this is kind of reinventing the wheel since we can already do that with a shared google doc.) The pro to adding a data structure is that the document has no single owner, and it's in a system that we are training everyone to interact with often. For interview notes, we could have interviewees apply through our intranet, so we have a profile of them that current eboarders can add notes to. (This would replace these onboarding notes and this form.) For budgets—I believe you already have an idea for budget tracking!
2. Continue using Google Docs. This will save an amount of design/implementation time, though I couldn't estimate how much. Another pro: people already know how to use Google Docs (though they usually don't). The biggest con is that this information is susceptible to being lost in members' Google Drives, but because I don't believe that this information needs to be carried over from year to year (with the exception of budgeting, which does), it wouldn't be a huge loss in my opinion. After all, we've kept meeting notes from the last few years, and reading through a lot of it was garbage without context that was only available to the people who were on the eboard at the time. As for the interviewing documents—one contained a field about pursuing rejected candidates in the future, but what is the likelihood that anyone will remember the document next year? It might as well be gone already. So, in conclusion:

• None of this information will live on the wiki.
• It would be great to build structures for this into the intranet.
• Google docs could suffice for a while longer if it isn't in the intranet.
• Redirects to the proper intranet pages or google doc templates could be put in the wiki, if anyone looks there for some reason.

3. Best practices, feedback, reflections, and ideas

I share @AbhiAgarwal's belief that the wiki is a good place to document best practices, which the smarties in the Infrastructure team should then work directly into the wiki as soon as possible. Whether this is coding statements like

Email X as soon as X is done.

as popups or

You should do X a week before.

as email reminders, I'm all for it! After reading all team's best practice documents from years past, I can confirm that best practices of this form are applicable across the board.

As for feedback/lessoned learned from specific events, there is definitely a need to build a mandatory feedback form into the intranet. Of course, there will have to be someone on the other end reading that information and then adding the new lessons into the wiki... I haven't thought this part through yet, but my reasoning is that it while it would be nice to have people add directly to the wiki, with the intranet we can enforce reflections and keep metrics on if an initiative is improving or not.

Lastly, these ideas/brainstorming docs. From what I could tell, they were done at the end of the year as a push towards the next year, but then no one ever looked back at them! :( For this reason, maybe there should be a type of document that sends itself out periodically to be reviewed.

Oh boy, you all know I never write this much. This section in summary:

• Document best practices in the wiki, with team-specific advice on each team's page.
• Build applicable best practices into the intranet in the form of reminders and functionality locks (e.g. you can't submit a reimbursement request for an event unless you've done a reflection form, etc.).

Because I can't emphasize it enough, like Abhi, I think email reminders from the intranet are a great idea!! An auto-manager of sorts that makes sure event planning is on track. I'm preaching to the choir here, but you're right that it's one thing to present people with a Best Practices Timeline and another thing to make them adhere to it.

[ethanresnick]

First off, thank you so much Katy for getting your hands dirty with this, diving into the admittedly-scary mess that is our Google Drive and also into the design literature! It's a huge, critical project and I really appreciate you taking it on.

I really like the categorization scheme you came up with from your content audit, and I think we've all now converged in our understandings of how these systems (i.e. intranet/wiki/drive) should interact at a high level.

1. Descriptions of things

I totally agree with everything in this section. Descriptions of the club's goals/history, which offer members context and motivation but aren't directly actionable, should live only on the wiki. As you also identified, maintainence will be a key challenge, so it's good you're thinking about that too.

2. Ephemeral content (Notes, interviews, budgets)

• None of this information will live on the wiki.
• It would be great to build structures for this into the intranet.
• Google docs could suffice for a while longer if it isn't in the intranet.
• Redirects to the proper intranet pages or google doc templates could be put in the wiki, if anyone looks there for some reason.

I agree with all of these points too. I'll comment more about each particular content type and intranet/Google Drive divide in issue #4.

3. Best practices, feedback, reflections, and ideas

You and Abhi have totally convinced me that all of the best practices need to exist as editable text, independent of whether a subset of them are later implemented in code. That way, the text version can act as the source of truth, which the code can follow (presumably with some lag time).

I'm still not 100% sure, though, on the format that editable text should take. In particular, I'm wondering: do/should the best practices follow any sort of template? (E.g. as I've thrown out before, maybe a good best practice always describes the experience/evidence that lead the user to create it?) Also, what types of groups could the practices best be put into? Is the division "team-specific vs. board wide", or is it more nuanced than that (e.g. maybe there are practices that apply to a bunch of teams, but not all, like, perhaps, some around event planning)? Etc.

I think analyzing, categorizing, and possibly templating the best practices will be the next big design step. That could determine the navigational structure of the wiki or even, perhaps, give rise to new intranet content types. (E.g. as you mentioned, a brainstorm might be a distinct type of content needing it's own treatment--or maybe not; maybe a brainstorm is just a combination of best practices with some resulting policy proposals, idk).

Re feedback: that's another complicated topic. Maybe you can open a separate issue on that, so we can discuss it in more depth?

Anyway, bottom line: I agree with essentially everything you've said and appreciate all your work on this. The next step seems to be more analysis on the types/treatment of best practices. And I'm so excited to see this to reality!