search

codeforboston / clean-slate-data

MIT License
27 stars 13 forks source link

DECISION: Most app documentation stays on the drive #72

Closed knod closed 4 years ago

knod commented 4 years ago

Why

We are proposing this because github might not be a great fit for all types of documentation:

  1. The team intro questionnaires of course can only work on the drive
  2. Sometimes being able to collaboratively edit in real-time is very useful. We've seen this in things like the 'PMing Asks' doc in the drive.
    1. Clicking on a user icon to navigate to where they are.
    2. Seeing text change in real-time.
    3. Editing the same document at the same time without worrying about conflicts blocking collaboration.
  3. The ability to comment on specific lines or words of a document can be useful in some circumstances.
  4. A table of contents is really useful to readers and google docs auto-generates them and makes them easy to update.
  5. When you change the title of a google doc, you don't have to go fixing all the links that were previously connected to it (which is what you have to do in a github wiki).
  6. Most people have a google account already (though there might still be problems with mobile devices like tablets and phones)
  7. To edit the wiki, I think you have to get added as a contributor - You don't have to get added to make issues, though
  8. People who don't know markdown will have to get help with that, which really slows down development time and adds to the reluctance of members who aren't comfortable with the technology and/or with asking for help.
  9. Wiki pages aren't searchable on github, unlike google drive documents. Issues are searchable, though.

How much do we want to mix the two? Keeping proposals, decisions, and tasks as issues seems like a good idea. Data seems to want whole-group docs in the github wiki, so that's a thing. Should everything else be on the drive? Or should we mix the two?

How

~See both ideas - idea 1 and idea 2.~ [Idea 1 was retired. See comments. Idea 2 was chosen.]

Idea 2

Less Mixed

Github issues

  1. Proposals/decisions
  2. Task items.
  3. Items needing a better/more explicit discussion history.
  4. Issue templates
  5. Wherever searching by label would be especially convenient.

Github Wiki

Whole-group documentation (living documents)

Google drive

Everything else (but more organized than it is now)

Resources

Proposal History

2020/03/??

  1. Idea 2 was chosen.
  2. Vote: I don't remember, but all 3 or above to at least experiment.

2020/02/06 pm

  1. Clarification added about whole group wiki pages being living documents.
  2. Identifies two ideas more distinctly.

2020/02/06

  1. Informal question asked in Slack.
  2. Proposal issue made with 'proposal' label and app label. Was posted to Slack (with end date, voting chart, and link to this issue), and post was pinned to the channel.
knod commented 4 years ago

Idea 1 was retired, idea 2 was chosen. For the record, idea 1:

Idea 1

Really trying to mix the two. Some documentation would be on github, some would be on google drive. This may be a bit more confusing than what we want.

Github issues

  1. Proposals and decisions.
  2. Task items.
  3. Docs that need a better history of discussion that goes on around them. Maybe the PMing doc really would be a good candidate for this. I'm not sure.
  4. Issue templates.
  5. Wherever searching by label would be especially convenient.

Github wiki

I'm have almost no specific thoughts and am open to ideas.

  1. Whole group intro docs.
  2. App Team landing page?
  3. Docs that won't be edited a lot.
  4. Docs that don't need a table of contents.
  5. Docs that can link to a bunch of other useful resources?

Github folders

Not sure either

  1. Docs that are basically just for reference.
  2. Docs that can't be edited, like PDFs?

Google drive

  1. Forms.
  2. Brainstorming/living docs that need to be collaborated on.
  3. Documents with formats that wouldn't be good in github files.

Unsure

  1. Spreadsheets
  2. Flow diagrams/images/pdfs, though I think you can see pdfs on github now.
  3. Old documentation that mostly needs preserving, but may be revived in the future.
knod commented 4 years ago

Votes unremembered. Maybe in meeting notes on a date before this last comment and after creation of proposal.

All were 3 or above for trying this out.