Doc week - proposal

Archive
1

Doc week - proposal

Kicking off this idea with a proposal! Welcome your thoughts/feedback :slight_smile:

Aims

Have a free week away from day-to-day activities to accomplish much needed tasks that are just never the most urgent, but still important to do.

Document/update anything and everything that will help us or our community to better do our work:

  • Processes
  • Technical specifications
  • Dev docs
  • Onboarding guides
  • Any critical information sitting with one person (i.e. a single points of failure)

Part of the exercise could also be reviewing that we have the right information architecture in place.

Timing

End of year seems like a good time as we wind down for the holiday season - but - don’t want to get in the way of development deadlines. How about the w/c 2nd December? Or we could easily move this into early 2020 if that feels like it will give more buffer around v1 launch/other priorities.

How it works

  1. In advance of Doc Week - all teams post a list of docs or projects they want to work on (including info about the task and what skills/help are needed, so people can get involved).
  2. Teams wrap up any urgent work in the week prior, and clear schedules during Doc Week.
  3. We tackle the list of documentation needs together, everyone’s free to work on anything on the list.
  4. Debrief at end of the week - teams can present back on what they accomplished.

Other considerations

  • Architecture and where we store docs - what will be the structure? E.g. revive the Wiki, use Google Docs, GitHub, or other. Probably needs a lot of consideration/consultation.
  • Who will be accountable for maintaining docs in future?
  • How do we spread knowledge to avoid single points of failure?
3 Likes
2

I wish we’d had this at the previous company I was working at (also doing blockchain). I was in charge of documentation there (among other things), but getting the engineering team to focus on that instead of bug-hunting or adding features was like pulling teeth. (and of course the engineering team were the only ones who understood it enough to help with the docs)

All of that in turn really delayed our developer outreach, because there’s no point in attracting devs to the project if they can’t work out how to use the damn thing!

2 Likes
3

Docusaurus looks good. I previously worked with Slate and a deprecated version of Gitbook, neither of which were ideal.

We ended up going with deprecated Gitbook for lack of a better option at the time (and not knowing about Docusaurus). One of our key considerations was self-hosting it, since company was based in China, and subject to the whims of the Great Firewall and whatever it arbitrarily chooses to block.

Most of these platforms use Markdown[1], so I’d recommend using any platform that supports Markdown to write the docs. Then it’s “just” a matter of migrating it over to the platform of your choice. Using Google Docs or MediaWiki would require an extra conversion step which would be its own headache (again, speaking from bitter experience)

[1] I’m assuming Github-flavored Markdown, though it’s worth checking to be sure. Markdown isn’t quite as standardized as I’d like.

4

Can confirm Docusaurus being awesome, especially because it easily integrates with Crowdin (auto-generated translation files + automatic PRs on translation submissions) for crowdsourced and easily bountyable translations. Our wiki is on Docusaurus: https://wiki.polkadot.network/docs/en/

It’s been a downright pleasure to work with and it renders locally very well so you can test changes on the fly.

3 Likes
5

Those auto-PRs on language translations are awesome! Would’ve been a lot of help when we were building Chinese/English bilingual docs at my last place

6

I can’t tell you the number of conversations we’ve had about this in the past. :persevere:

I’m very much in favor. If other team members (namely the ones who we need for docs!) are on board, I’d suggest we plan in this buffer time after v1 goes live.

We might also reserve some time to work on our automated test coverage, another chore that came up in Istanbul.

2 Likes
7

Thinking maybe like last week of Jan 2019/ early Feb might make sense for this?

8

I think so, too, @ceri as today we’re a day past our v1 release cut off target and still finalizing features. :slight_smile: Our goal is still to submit the app by the first week of January.

That said, perhaps we could carve out time between release submission & publication (mid-Jan).

What do you think @andre?

1 Like